GET/privacy.txt
PublicprivacyTxtRedirect (303) to the canonical privacy policy on bringyour.com. The api serves the redirect so a client that only knows the api host can still reach the policy.
URnetwork 完整实现了 UR 协议运营方规范。 UR 协议 ↗
Redirect (303) to the canonical privacy policy on bringyour.com. The api serves the redirect so a client that only knows the api host can still reach the policy.
Redirect (303) to the canonical terms of service on bringyour.com.
Redirect (303) to the vulnerability disclosure policy on bringyour.com.
The api's robots.txt, which disallows only /lag/. A crawler that renders lag.dev runs its script, and each render would otherwise create a lag.dev guest network and open measurement sessions. Every other path stays open to crawlers.
The serving status of the api process that answered, used by the deploy poll and by fleet status sampling. status is a latched value rather than a per-request health check, so this route stays O(1) and never couples a deploy poll to database load: "ok" while the process serves, a string beginning error while it is not ready (which fails a deploy poll), and "draining" from SIGTERM onwards (deliberately not an error, so an operator-initiated drain is not counted as a service error). host, service and block name the process that answered, and client_ is the caller address it observed.
The process's build version; absent when it has none.
The deployed config version; absent when it has none.
The latched serving status: "ok", "draining" from SIGTERM onwards, or a string beginning "error" while the process is not ready (which is what fails a deploy poll).
The caller address this process observed.
Get the cumulative destination-reported bytes for contracts finalized on or after the start of subnet block 9. The counter advances when contracts reach a final outcome and is intended for public clients polling every 1-5 seconds.
Base-10 destination-reported bytes for contracts finalized since since_block. This is a string so clients do not lose integer precision as the lifetime total grows.
First subnet block included in the counter.
UTC start time of since_block.
The public health status of the network, as the ur.io status pill and banner show it. status is healthy; one of degraded, partial, major or full, the level an operator set while fixing a problem; or unknown when the status cannot be read. A level other than healthy carries reason, one line of public text, and since and updated: when the network left healthy and when the level or reason last changed. No other field is set.
Each API process keeps a status it read for 10 seconds. A known status may be cached for 30 seconds (Cache-Control: public, max-age=30); unknown is not cached. This is not a readiness check: /status is.
healthy, a level an operator set (degraded, partial, major, full, mildest first), or unknown when the status cannot be read.
What is wrong, as one line of public text. Set for a level other than healthy.
When the network left healthy, in UTC. A change of level or reason keeps it.
When the level or reason last changed, in UTC.
The operator's public seed bundle (EXTENDER-UPDATE2.md §2): the serialized ExtenderSeedEnvelope, raw bytes, at most 64 KiB. It is the origin the seed mirrors copy, and every mirror serves the same bytes at this same path for one sequence. A client reads at most 64 KiB + 1 bytes, refuses a larger body before decoding, and verifies the envelope and every record in it under the root keys its network space already authorizes (VerifyExtenderSeed); nothing here is trusted for being served by the operator.
The bundle is public by design: a small, stable cohort of ordinary open-tier records with an empty canary channel, and root-signed revocations. It never carries a gated or channel-restricted record, a root key, a network host setting or a resolver setting.
No auth. 404 while the operator's seed is off or nothing is stored; 503 while no stored bundle verifies. The answer is cacheable for five minutes, and its strong ETag is the quoted hex sha256 of the body.
Send a Services inquiry, about embedding URnetwork or any custom use of it, to the URnetwork team. This is the endpoint behind the Services page form, and it needs no authentication. Requests are rate limited per source address.
Expected monthly active users of the embedded or custom deployment.
Expected total monthly data budget, in bytes.
Optional notes about the use case.
Apply to host a Friends of the Network research node: a Raspberry Pi the URnetwork research team runs network tests on. This is the endpoint behind the ur.io Friends of the Network form, and it needs no authentication. Applications are not stored by the api; they are forwarded to the URnetwork team. Requests are rate limited per source address.
ISO 3166-1 alpha-2 country the node would be hosted in. Nodes ship under US export controls, so some countries are refused.
The applicant agrees to do their best to keep the node online. Must be true.
Credit the applicant in the published research reports.
The name to credit, when it differs from name.
Up to two t-shirts.
m for men's fit, f for women's fit.
Up to two hoodies.
m for men's fit, f for women's fit.
Optional notes, comments or questions.
Upload a log file for the caller, associated with a feedback id. The request body is the raw log file content, streamed to storage. Note the {clientId} path segment is actually the feedback id the log is attached to.
udid. The feedback id the log file is associated with.
Set, with a 200, when the upload was refused: over the per-network rate limit (one upload per network per period) or over the size limit.
The catalog an agent can buy from, so a skill can discover it without triggering a 402. Prices come from the Pro price list, never from the x402 configuration, so an agent is quoted the same number a human pays on any other rail; a sku with no price is not offered at all. It names the x402 protocol versions spoken (v2 and v1), each network's x402 v2 (CAIP-2) id, and each sku's exact amount in atomic units of the asset, from which an agent sets its client's per-payment cap: x402 clients refuse a payment over $1 by default.
The skus are pro_1month, data_1tib, data_10tib and data_256gib. data_256gib is 256 GiB of data for $0.75 (amount "750000"): the pack for clients with a $1 per-payment cap, such as Cloudflare Agents' withX402Client, which cannot raise it. It is sold only over x402 and with Gamma, and it adds data only: it does not lift a limit that UR Pro lifts.
The newest x402 protocol version spoken, 2.
Every x402 protocol version spoken, newest first.
The networks, by name, as x402 v1 and X402PurchaseArgs. name them.
Each network's x402 v2 id (CAIP-2), by name.
pro_1month, data_1tib, data_10tib or data_256gib (256 GiB for $0.75, the pack for clients with a $1 per-payment cap, sold only over x402 and with Gamma).
The price in atomic units of the asset, exactly as the terms quote it (USDC has 6 decimals: "5000000" is $5.00).
True for the Pro-month sku, which grants the Pro entitlement. The data skus never do.
Buy a sku inline, over x402 v2 or v1. Without a payment the answer is 402 carrying the payment terms: x402 v2 in the PAYMENT-REQUIRED header (base64 JSON, networks as CAIP-2 ids such as eip155:8453) and x402 v1 as the body. The agent signs one of them and retries the SAME request with the signed payment in PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1), which is settled and granted. The receipt is the body and, in the payment's version, the PAYMENT-RESPONSE (v2) or X-PAYMENT-RESPONSE (v1) header. Requires a network session.
The terms' error states the price. The x402 SDK clients refuse any payment over $1 unless their per-payment cap is raised (maxAmountPerPayment; maxPaymentUsdc in Coinbase AgentKit), so an agent raises the cap to the price first. A client that cannot raise it can buy data_256gib, 256 GiB of data for $0.75.
A v2 payment's accepted terms must equal one of the quoted terms (every field but extra, which must hold the quoted extra). A malformed payment, or one sent in both headers, is answered 400. A payment the terms or the facilitator refuse is answered 402 with the terms again, the reason as their error (in v2 the x402 error code), and for a refused settlement its SettlementResponse in the receipt header. A settlement the facilitator broadcast but could not confirm (settlement_) grants nothing yet and is recorded: do not sign another payment for it.
The same 402 round trip is also carried inline by POST /network/, where an agent meets the plan's limits, for an agent that asks for terms with X-UR-X402: 1. An agent that did not ask reads error. there and can buy pro_1month here, then retry, or pay on its auth-client retry.
The signed x402 v2 payment for terms previously quoted by a 402: base64 of the JSON PaymentPayload, naming the terms it accepted.
The signed x402 v1 payment for terms previously quoted by a 402: base64 of the JSON PaymentPayload. Send one payment header, not both.
A sku of GET /x402/skus.
The network the agent intends to pay on, by name. Must be one that was quoted. Optional when only one is configured, and for an x402 v2 payment, which names its network itself.
Where to send the receipt. Optional.
The network, by name, whichever x402 version paid.
The paying wallet, as the facilitator reported it.
The x402 protocol version the payment was made in.
What the scheme needs to build the payment: the token's EIP-712 domain (name, version) on EVM networks, the facilitator's feePayer (and transactionVersions, when it names them) on Solana.
The services document that SN25's on-chain service record (set_service on the owner hotkey) points at, in the Bittensor services format: what URnetwork serves, where its API and this spec are, and how it is paid for, by SN25 gamma (gamma) or over the x402 header protocol (x402, see /x402/skus). Readers skip fields and types they do not know. max_spend is the most one gamma charge takes. Served with Access-Control-Allow-Origin: *, so web apps can read it. Unauthenticated.
Always 1.
The published services that may point at this document.
The SS58 hotkey the service is published under (SN25's owner hotkey).
openapi
Where this OpenAPI spec is published.
gamma (SN25 gamma deposits) or x402.
gamma: the most one spend takes, in gamma (an exact decimal string).
gamma: GET /pay/gamma/terms.
x402: GET /x402/skus.
What paying with SN25 gamma takes now. Gamma is a Bittensor chain feature, not an app or a wallet: a coldkey mints a subnet's gamma by burning its alpha (bought with TAO, or taken from stake) into a deposit keyed by a hotkey, one gamma per US dollar, and the subnet's service spends it. URnetwork accepts SN25 gamma only.
available: purchases are on. Otherwise unavailable_ reason: not_ configured, chain_ unreachable (the biller cannot read the chain, or has not run for three minutes), runtime_ unsupported (the chain runs a runtime whose Gamma calls or events are not as reviewed; billing pauses until it is reviewed), service_ not_ published, service_ spender_ mismatch, billing_ proxy_ missing, fee_ float_ low, watcher_ behind or batch_ in_ review.mint_ available: minting works now. Otherwise mint_ unavailable_ reason: gamma_ disabled (off network-wide), subnet_ gamma_ disabled (SN25 has not switched gamma on), price_stale (the chain's TAO/USD oracle last fed more than max_ price_ age_ blocks, 300 blocks, ago: every mint fails with TaoUsdPriceUnavailable until it feeds again; pay with a coin or x402 meanwhile). A deposit that already holds the price can still pay while minting is off.items: each plan and data pack at the caller's price tier, with its price in gamma (one gamma per dollar), the daily spend cap a deposit needs for it (min_ daily_ cap_ gamma: a spend takes its whole amount or is skipped, so the cap must allow the price), and an indicative TAO amount (indicative_ tao) from the chain's own simulation of a mint, plus 3%; "" while minting is off. Plans renew (renews).auto_ min_ daily_ cap_ gamma: the daily cap that lets every automatic charge (a renewal, a top-up, a seat upgrade) be spent.disclaimer is the wording every surface shows; automatic_ says what is charged automatically. Unauthenticated.
The SS58 account every URnetwork deposit names as its spender.
The oracle's accepted TAO/USD price, in dollars; "" before any feed.
Blocks since the oracle last fed.
A mint needs a feed at most this old (300).
The smallest mint, "0.1".
A data pack Gamma sells. data_256gib is 256 GiB for $0.75, the pack for clients with a $1 per-payment cap; it is sold only with Gamma and over x402, never by card or with the crypto invoices.
The price in gamma, one gamma per US dollar.
The daily spend cap a deposit needs for this item.
Plans renew automatically from the deposit unless turned off.
About the TAO that mints the price now (the chain's simulation, plus 3%); "" while minting is off.
The daily cap every automatic charge needs.
Start a purchase paid from the signed-in network's SN25 gamma deposit: Pro monthly, yearly or yearly_ (the welcome offer, while redeemable), or a data pack (data_1tib, data_10tib, or data_256gib: 256 GiB for $0.75, sold only with Gamma and over x402), to the network (delivery account) or as a balance code (delivery code, data packs only; with email, the code is emailed too). Give exactly one of plan and item_id. The price is the card price in US dollars at the caller's tier (the 256 GiB pack's is the same on both rails that sell it), and one gamma is one dollar, so amount_gamma needs no rate.
The answer names deposit_: the hotkey URnetwork assigned this account, on netuid 25. It is not a pay-to address, and there is no wallet URI: never send TAO to it. Mint into it with your coldkey, previewing first (mint_, then mint_command):
btcli tx mint-gamma --netuid 25 --hotkey <deposit_hotkey> \
--amount-tao <TAO> --service-hotkey 5CyQFykVpfa9xgZVGgBsiNUpjbo1EihBTSkPvDC1FZbL1wxG --dry-run--service-hotkey names URnetwork's spender for a new deposit, and refuses a deposit that names another. The mint is the only step outside this API, and the only signature: the bearer token is the only authentication, since whoever mints into this account's hotkey pays for this account. The same hotkey serves every later purchase; each purchase has its own 32-byte reference, which our spend carries.
Once the deposit can pay (its spendable gamma covers the price), the biller spends exactly amount_gamma with spend_gamma and credits the purchase only when that spend is finalized. A spend the chain skips (the gamma moved away, the cap, another spender) buys nothing, and is tried again only after the deposit changes. Poll /pay/gamma/status with status_token, a bearer secret for this one purchase (keep it out of urls and logs).
A payer whose coldkey cannot open a deposit at this hotkey (another coldkey already owns that deposit, or the hotkey: the mint fails with NonAssociatedColdKey) asks again with coldkey, and gets a hotkey that coldkey can use. An open purchase of the same item for the same hotkey is returned again, with a new status_token.
Paying with gamma turns on, by default, the automatic renewal of a plan paid with gamma and the automatic data top-up and seat upgrade (/pay/gamma/settings). min_ is the daily cap this purchase needs; auto_ the cap the automatic charges need.
A plan is never charged for days another Pro payment pays for:
already_ subscribed); a prepaid crypto year refuses nothing. A plan started before such a subscription began waits while it pays for the days the plan would buy, and is charged only if it ends before the purchase expires.already_ subscribed): that spend may still land, so it cannot be voided. Asking again for the purchase being charged returns it. Check again in a few minutes.already_ subscribed).Otherwise a plan bought while the network has a paid Gamma plan starts at once, as an upgrade; the rest of the paid term is not carried over. A data pack is not Pro, and is sold beside any of these.
A refusal returns error with a 200 (GammaPaymentError): invalid_, asset_ (purchases are off, or minting is off while the deposit cannot already pay: mint_ says why), plan_, item_, guest_ (plans only), offer_, already_ (plans only: another Pro subscription renews, or a Gamma payment for the network's Pro plan is being charged), invalid_, deposit_ (every hotkey of the account belongs to another coldkey), rate_limited or start_failed.
Gift codes (a year of Pro each) are bought from the same deposit with /pay/gift/gamma-intent.
A data pack Gamma sells; data_256gib is 256 GiB for $0.75.
account (the default) or code (data packs only).
Delivery code: where the code is also emailed.
The SS58 coldkey that will mint, to get a hotkey whose deposit it can open or owns.
The purchase's bearer secret, for /pay/gamma/status.
The data pack, or gift_ for a gift order's codes (/pay/gift/gamma-intent); "" for a plan.
account or code; a gift order's is code.
The price in gamma, exactly what our spend takes.
The purchase's public 32-byte spend reference (0x hex), carried by our GammaSpent.
The SS58 hotkey to mint into. Not a pay-to address; never send TAO to it.
About the TAO that mints what the deposit still needs (at least 0.1 gamma); "" while minting is off.
With review: voided or credit_; else "".
The deposit's balance as last seen; "" when there is no deposit.
The balance within what the daily cap allows now; "" when there is no deposit.
How much more gamma the deposit needs for the price.
The deposit's daily spend cap; "" for none.
The finalized block of our GammaSpent.
A paid data pack's code, for delivery code; always "" for a gift order (/pay/gift/gamma-intent), whose codes are on its cards.
Plain TAO sent to the deposit hotkey by mistake, in rao.
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
The state of a gamma purchase, read with its status_token, in the words of /pay/crypto/status. status, first match wins:
unknown: no such purchase, or the token does not match.paid: credited, on our own finalized GammaSpent that carries reference (spent_block). Never on a mint alone. balance_code is set for a data pack's delivery code; a gift order's (/pay/gift/gamma-intent) stays empty, since its codes are on the order's cards (/pay/gift/order).review: an operator looks (review_ reason voided, or credit_ failed: the spend landed and the credit keeps failing).confirming: our spend is pending or landed and the credit is being written, or the deposit covers the price and the next biller run spends it.expired: past expires_at with nothing spent (quote_ expired). Unspent gamma stays in the deposit for the next purchase.seen (pending with no gamma at the hotkey yet) with error.code already_ subscribed. Another payment pays for the days the plan would buy, so it is not charged now, whatever the deposit holds; error. message says which: another Pro subscription pays for or still bills those days (the plan is charged only if that one ends before expires_at), another Gamma payment for the network's Pro plan is being charged (if that one is paid, this one is not), or another Gamma plan was paid after this purchase started (it is never charged; unspent gamma stays in the deposit).seen: the deposit holds gamma but cannot pay yet: less than the price (remaining_ gamma is how much more to mint), a daily cap below the price (daily_ cap_ too_ low; raise it to at least min_ daily_ cap_ gamma), another spender (wrong_ spender; point it back with btcli gamma set-spender --netuid 25 --hotkey <deposit_ hotkey> --service-hotkey <service_ hotkey>), or our last spend was skipped (error.code from the chain's reason: insufficient_ gamma, daily_ cap_ exceeded, wrong_ spender, no_deposit), tried again only after the deposit changes.pending: no gamma at the hotkey yet.Amounts are exact decimal strings of gamma (10^9 units per gamma), as the biller last saw the deposit (observed_). stray_ is plain TAO someone sent to the deposit hotkey: a mistake (TAO sent to a hotkey does not pay); write to support@ur.io to have it returned. Unauthenticated, per-ip rate limited.
With review: voided or credit_; else "".
The deposit's balance as last seen; "" when there is no deposit.
The balance within what the daily cap allows now; "" when there is no deposit.
How much more gamma the deposit needs for the price.
The deposit's daily spend cap; "" for none.
The finalized block of our GammaSpent.
A paid data pack's code, for delivery code; always "" for a gift order (/pay/gift/gamma-intent), whose codes are on its cards.
Plain TAO sent to the deposit hotkey by mistake, in rao.
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
The network's automatic gamma charges. Both switches are on by default for every account that pays with gamma:
auto_renew: at the end of each term of a plan paid with gamma, charge the plan's current price from the deposit (renew_plan; a welcome-offer year renews at the yearly price). Not while another Pro subscription of the network pays for or still bills those days (the App Store, Google Play, or a card subscription, also one whose renewal Stripe is still retrying): the renewal waits, and when that one ends within the term's 30-day grace, the new term starts where it ended. A Gamma plan bought while the renewal waits replaces it (/pay/gamma/intent).auto_topup: when the data balance runs out, or will within the next check, buy topup_ item_ id (data_1tib unless set; any pack Gamma sells), at most one an hour; and when a free account hits its client limit (client_ limit_ exceeded with upgrade_ required), buy Pro (renew_plan, else monthly), at most once a day, while auto_renew is on too (an upgrade is an automatic Pro charge), and unless another Pro subscription already pays for or still bills now. A Pro account at its limit gets the error as before. An automatic upgrade never changes how the network provides; a Gamma plan bought while it waits replaces it, as it does a renewal.monthly_ caps what the automatic charges take in a calendar month (UTC; "" for no limit); month_ is this month's so far. Each automatic charge is one purchase per (account, purpose, period) with its own reference, is spent from deposit_ (the hotkey that paid last), sends a receipt email, and when the chain skips it, one notice; it is tried again only after the deposit changes. charging lists the automatic charges whose switch is off that were already being charged when it was turned off (see POST), and notice says it in a sentence. Network credential only.
The automatic charges whose switch is off that were already being charged when it was turned off: their payment was sent to the chain (or landed and is being credited), so each can still be charged this once, and none after it while the switch is off. Empty when there is none. A charge not yet sent when its switch was turned off is cancelled and never listed.
renew (the renewal at the end of a term), topup (a data top-up) or seat (the upgrade to Pro at the client limit).
The plan it buys; "" for a data pack.
The data pack it buys; "" for a plan.
confirming: its payment was sent to the chain, or landed and is being credited.
charging in a plain sentence for the customer; absent when it is empty.
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
Set the automatic gamma charges' switches (see GET), the top-up item (data_1tib, data_10tib or data_256gib) and the monthly limit (a decimal amount of gamma; "0" or "" removes it). A field left out is unchanged. The answer is the settings as they now are; a refusal returns error and applies nothing in the request: item_, invalid_, or already_ for auto_renew: true while another Pro subscription of the network renews (the App Store, Google Play, or a card subscription, also one whose renewal Stripe is still retrying): both would bill the same days. That answer carries the settings unchanged. Turning automatic renewal off is always allowed. Network credential only.
Turning a switch off cancels the open automatic charges it governs that are not yet sent to the chain: the renewal waiting at the end of a term (auto_renew), a data top-up (auto_topup), and an upgrade at the client limit (either switch). They are never charged, and turning the switch back on makes them again for the same term, hour or day. A charge already sent to the chain cannot be recalled, and is not cancelled: the switch is still turned off, and the answer lists that charge in charging (status confirming) and says in notice that it can still be charged this once, and none after it while the switch is off. If its payment lands, it is credited as usual (a renewal adds its term).
The data pack an automatic top-up buys, any pack Gamma sells.
A decimal amount of gamma; "0" or "" removes the limit.
The automatic charges whose switch is off that were already being charged when it was turned off: their payment was sent to the chain (or landed and is being credited), so each can still be charged this once, and none after it while the switch is off. Empty when there is none. A charge not yet sent when its switch was turned off is cancelled and never listed.
renew (the renewal at the end of a term), topup (a data top-up) or seat (the upgrade to Pro at the client limit).
The plan it buys; "" for a data pack.
The data pack it buys; "" for a plan.
confirming: its payment was sent to the chain, or landed and is being credited.
charging in a plain sentence for the customer; absent when it is empty.
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
Fetch the published Ed25519 public key for a client id. Unauthenticated by design - the value is a public key meant to be fetchable by any peer. A client that has never published a key returns {"public_ with HTTP 200.
udid. The client id to look up.
base64 encoded Ed25519 public key for the client id. null when the client has never published a key.
Fetch the operator-signed registration history of a client's public key: the ordered signed registrations, generation 1 first, each an opaque serialized registration exactly as the operator signed it. A peer verifies the chain itself -- every entry must be signed by a trusted signer under the deployment domain, generations must be contiguous and each entry must commit to the hash of the one before -- and compares the key it ends on with the one the platform attached to a contract, which is what turns the platform's key distribution from something a peer must trust into something it can check (connect/DESIGNNOTES3.md).
Unauthenticated by design, matching GET /key/: every byte returned is already-published signed evidence. A client with no signed history -- a legacy client, or an operator that does not run the signed path -- answers {"history": []} with HTTP 200, never an error: an error is an availability signal, and a consumer must not confuse the two. At most 64 registrations, and at most 1 MiB, are returned.
udid. The client id to look up.
The ordered signed registrations, generation 1 first, each the base64 of one opaque serialized registration. Empty when the client has no signed history.
Simple hello to the network that returns some useful information. This can be used for discovery.
It is also the extender network's trust root: extender_ are the keys whose record signatures this network space accepts, and gossip_ names the operator's gossip node. Both arrive over the platform's pinned tls, so a client can refresh them even when the request itself travelled through an untrusted extender -- and the extender activation probe forwards a real GET /hello through the candidate's tcp carrier to prove the forward works.
The extender root keys whose record signatures this network space accepts, hex encoded. It arrives over the platform's pinned tls, so it is trustworthy even when the request itself travelled through an untrusted extender, and it REPLACES whatever list the client had stored. Absent when the operator has configured no extender network.
The libp2p peer id of the operator's gossip node, derived from its gossip identity key. A member dials the operator only when it knows this id, since without it there is nothing to authenticate the far end of the dial against -- so an operator running no gossip service serves none rather than an address a member could not verify.
Information about the caller's IP as seen by the platform: its geolocation, and whether the IP is currently connected to the network.
The location comes from MaxMind GeoLite2 City, and the network the ip is announced by (asn) from GeoLite2 ASN when the operator has it. This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com. The database has no privacy/VPN classification, so none is returned.
city and region are left out when the IP is not located that precisely, e.g. only to its country.
The largest subdivision, e.g. a state.
ISO 3166-1 alpha-2, lowercase.
Two-letter continent code, lowercase.
IANA time zone, e.g. Europe/.
The autonomous system the ip is announced by, from MaxMind GeoLite2 ASN (lag.dev/PLAN.md A3). Left out when the operator has no ASN database or it has no record for the ip.
Create a lag.dev guest: a guest network marked to expire, with one client, and answer that client's JWT (lag.dev/PLAN.md A1). lag.dev keeps the JWT and reuses it until expires_at, when the operator removes the guest network and the JWT stops working (A2).
No credential. Any request body is ignored; lag.dev sends {}. Guest sessions are limited to 10 an hour per /24 (IPv6 /48) of the caller, shared by everyone in it. A refusal is a 200 with error: limit with the rest of the window in retry_, or unavailable when the guest could not be created.
The guest client's JWT, for /lag/ and /lag/track.
When the guest is removed and the JWT stops working: RFC 3339, whole seconds, UTC.
limit: a rate limit or a cap was reached. unavailable: there is nothing to answer with now.
How long to wait before asking again; 0 when there is no wait to name.
A sample of up to 64 extenders that serve the lag.dev measurement API now, randomized per request and spread across countries (lag.dev/PLAN.md A4). An extender is offered only while its measurement certificate is issued, unexpired and not withdrawn, and its measurement name is published, meaning Route 53 answers for it (C8): an extender that is deactivated, gated, a canary, opted out by its owner, waiting on a new certificate request, or whose name is not yet published is not.
There is one entry per extender. host is its measurement name, its id under the measurement zone, which resolves to its active addresses ips, IPv4 first, so the browser connects to the name on whichever family it has. location is where the operator places it: its derived location, else MaxMind GeoLite2 City for its first address. These extenders are already public through certificate transparency and DNS.
Requires a CLIENT jwt, the lag.dev guest's or any other client's.
The extender's ed25519 identity key, hex.
The extender's measurement name, <extender_, which the browser connects to.
The extender's active addresses, IPv4 first; the name resolves to these.
ISO 3166-1 alpha-2, lower case.
Every ticket of a lag.dev track in one call (lag.dev/PLAN.md A6). A track is up to 12 extenders, the 8 dots and then up to 4 spares; a ticket's position is its extender's place in the request. Each ticket admits one measurement session on its extender: it must open within 2 minutes (expires_at), and once open it pings for as long as the browser keeps it, with at most one load of 5 s down and 5 s up. Tickets are signed by the operator's root key, the one that signs extender records. An extender that cannot be measured now is left out, so a position can be missing; none at all is unavailable.
With track_id, the call reissues tickets in that track instead, for a dot whose session dropped, so it reconnects without leaving its track: each extender is given with its position, and each pair must be one the track already holds. Only the client the track was issued to can reissue it, within an hour of its issue. A track gets one reissue per position and 8 in all; past either, the call is refused with limit. An unknown track, another client's, an older one, or a pair the track does not hold is unavailable.
Requires a CLIENT jwt. New tracks are limited to 12 an hour per client, 60 an hour per /24 (IPv6 /48) of the caller, and 30 an hour per signing agent (a request's Signature-Agent, Web Bot Auth), wherever that agent's browsers run; reissues do not count toward them. A refusal is a 200 with error.
A new track keeps the caller's network (its autonomous system) and the GeoLite2 City place of the caller's address, with the city's coordinates when the place names a city, looked up when the track is issued. The address itself, a prefix of it or a hash of it is never stored. A track from a signing agent, or from an address in a hosting or cloud network, is marked automated, with which of the two it was and nothing more; its results count in no aggregate.
The lagdev command line and MCP server name themselves with an X-Lag-Client header, cli or mcp, and the track keeps which client ran it. A browser sends none, which means web; the header is not among the allowed CORS request headers.
Set to reissue tickets in a track issued to the caller within the last hour.
The 8 dots, then up to 4 spares.
For a reissue, the dot's position in its track. Ignored for a new track, whose positions are the request order.
The extender's measurement name, which the session connects to.
The dot's position in the track, 0-7 for the dots and 8-11 for the spares.
The ticket text for the session url: base64url, without padding, of the signed LagTicket.
Every session must open before this: RFC 3339, whole seconds, UTC.
limit: a rate limit or a cap was reached. unavailable: there is nothing to answer with now.
How long to wait before asking again; 0 when there is no wait to name.
When paying for a subscription with Stripe, create the payment intents, ephemeral key, and customer id needed to complete the purchase. A legacy guest network (no sign-in method) is refused with error.code guest_ (PurchaseError); a payment that could not be started with start_failed.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
Create a Stripe customer portal URL for the caller to manage their subscription. A refusal carries a stable error.code (SubscriptionError: no_customer, store_) beside its error..
A stable code for the refusal, so a client can pick a localized message. One of: managed_: the App Store bills this subscription; cancel it there (manage_url). managed_: Google Play bills this subscription; cancel it there (manage_url). does_: a one-time crypto payment (USDC, Zcash, Monero, TAO, Bitcoin, ETH or SOL) covers one period and never renews, so there is nothing to cancel. not_: a store the server cannot act on. For a plan paid with Gamma, turn renewal off with POST /pay/ (auto_renew: false); manage_url explains it. no_: no Stripe subscription is billing this network. no_customer: this network has no Stripe customer, so there is no billing portal. store_: Stripe did not answer or refused the change; a retry may work. Absent from older servers; clients fall back to message for an absent or unknown code.
Buy a data pack with a card without signing in (the ur.io buy-data page). Starts a hosted Stripe checkout and returns the url to send the customer to. To pay with USDC on Solana use /pay/data/solana-intent.
With network_name, the data is applied to that network by the payment webhook as soon as the payment confirms, and the customer is emailed a note that the data is on the network (the code is included, already applied). The name is matched case-insensitively and exactly; an unknown name returns error.code network_ with error. No network named <name>. Every refusal carries a stable error.code (PurchaseError) beside its error..
Without network_name, the customer receives a data code by email, as before. Stripe collects the email on its checkout page when email is not given.
The success url is the configured checkout success url plus item= and, when applying to a network, network=. Unauthenticated, per-ip rate limited. Errors are returned as error. with a 200.
the hosted checkout; omitted or empty means stripe
the network that receives the data; omit to receive a code by email
where the code (or the applied note) is sent; Stripe collects it at checkout when omitted
the hosted checkout url to send the customer to
the resolved network when network_name was given
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
Whether a network with exactly this name exists, for the buy-data page. Matched the same way /pay/data/checkout resolves network_name (case-insensitive, exact). Unlike /auth/network-check, which is a sign-up similarity check, a name within a few characters of an existing one is NOT reported as existing. Returns only the canonical name, no id. Unauthenticated, per-ip rate limited.
the name as stored, when it exists
Buy a data pack with USDC on Solana, without signing in or giving an email: the data goes straight to the network named by network_name (matched like /pay/data/network-lookup). Records the payment intent and returns the exact amount_usd to send in USDC and where to send it: recipient (the receiving address, the same one /solana/payment-intent quotes) and spl_ (USDC). The client generates reference (a Solana Pay reference: a fresh base58 public key) and either opens a Solana Pay url built from these, or shows the buyer recipient, the amount and memo (which is the reference) to send by hand from any wallet or exchange. A client keeps no address of its own: a result without recipient (from a server that predates it) cannot be paid. The Helius webhook (/pay/solana) matches the transfer by the reference among the transaction's account keys OR by the memo text, then lands the data on the network (data only, valid for one year, no Pro) and emails the network's admin when their login is an email. A transfer with no reference and no memo (a wallet that cannot add one) is matched by its exact amount_usd, which is unique among open quotes: it is credited only when it is the one USDC transfer to our receiving address and exactly one open intent was quoted that amount, sent between the quote and expires_at. Anything else is recorded for support to credit by hand.
The intent expires after 24 hours (expires_at); a payment that carries the reference or memo and arrives late still credits as long as the intent has not been swept. A reused reference, an unknown item or an unknown network return error. with a 200, and a stable error.code beside it (PurchaseError: invalid_, network_ and the others). Unauthenticated, per-ip rate limited (rate_limited).
the network that receives the data
the Solana Pay reference the client generated (a fresh base58 public key); it doubles as the transfer memo for a payment sent by hand
- the exact amount to send, in USDC: the data pack price plus a unique sub-cent suffix (0.000001 to 0.009999, in USDC's 6 decimals) that identifies a payment sent without the memo, so show and pay every decimal
the transfer memo for a payment sent by hand (the reference)
the resolved network name, as stored
the merchant address (base58) to pay, the same one /solana/payment-intent quotes; build the payment url and show the address from this, never a hardcoded address
the SPL token mint (base58) to pay in (USDC)
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
The state of a data pack payment started with /pay/data/solana-intent, for the buy-data page to poll while it waits: pending until the USDC transfer is credited, paid once the data is on the network, expired when the intent passed expires_at unpaid, unknown for a reference that is not a data pack intent (plan intents made by a signed-in wallet are not reported here). Unauthenticated, per-ip rate limited.
The coins the server takes payment in now, and what each sells: usdc_solana (USDC on Solana), zec (Zcash, to shielded addresses only), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) and sol (native SOL). assets lists only the coins that can be paid with now, so a coin that is switched off, or whose quotes the server refuses for now, is not in it; a client never offers an asset or an item assets does not name. The order means nothing: the apps show Card, then USDC, Zcash and Monero, then "More coins" with TAO, Bitcoin, ETH and SOL. No asset sells monthly, which is card only.
Each entry names the coin's network (the chain to send on), its atomic decimals, the most decimals a quoted amount has (quote_: 8 for btc, 6 for every other coin) and whether its invoices carry a payment link (payment_link: false for tao, which has no payment link standard).
A coin that is on but cannot be paid with now is in unavailable_ instead, with available: false and an unavailable_, for a page that shows it as temporarily unavailable: its scanner lags the network, has stopped, or does not know a height; its backend is not configured (not_: TAO, Bitcoin, ETH and SOL each need their chain source and the key that makes their deposit addresses); its address pool is empty; or its rates were found stale or too far apart lately. It is never offered: /pay/crypto/quote, /pay/crypto/intent, /pay/data/crypto-intent and /pay/crypto/requote refuse it with asset_, from the same decision.
To pay through the API alone: read this list, price an item with /pay/crypto/quote, make the invoice with /pay/crypto/intent (signed in) or /pay/data/crypto-intent (a data pack without signing in), send exactly amount to address on network (or open uri), and poll /pay/crypto/status with the invoice's status_token until paid.
The assets list rides on /subscription/balance as crypto_, and unavailable_ as crypto_. Unauthenticated, per-ip rate limited.
The assets that can be paid with now, the only ones a client offers; empty when no coin can be.
A coin a crypto invoice is paid in: usdc_solana (USDC on Solana), zec (Zcash, shielded), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) or sol (native SOL). TAO, Bitcoin, ETH and SOL are received into a Coinbase deposit address of each invoice's own and credited from the chain.
the chain to send on; absent from older servers
The chain a coin is paid on: solana (usdc_solana and sol), zcash, monero, bittensor (tao, the Finney network), bitcoin and ethereum (eth, Ethereum mainnet only). A coin sent on another network is not credited.
The decimals of the coin's atomic unit: amount_ is amount × 10^decimals (6 for USDC, 8 for Zcash and Bitcoin, 9 for TAO and SOL, 12 for Monero, 18 for ETH). Absent from older servers.
the most decimals a quoted amount has (8 for btc, 6 for every other coin); absent from older servers
Whether the coin's invoices carry a payment uri: false for tao, which has no payment link standard (the invoice gives the address and the amount, and uri_note says so). Absent from older servers.
the plans the asset sells (yearly, yearly_); never monthly
the data packs the asset sells (data_1tib, data_10tib); never data_256gib, which is sold only over x402 and with Gamma
the confirmations a payment needs before it is credited (for TAO, ETH and SOL, 1 is a finalized block)
how long a quote holds, in seconds
Whether the asset can be paid with now: true for every asset of assets and of crypto_, false for one of unavailable_ and crypto_. Absent from older servers, which listed only assets they would sell.
Why an asset that is on cannot be paid with now; absent when it can. scanner_: its scanner has not succeeded within three scan intervals (or never), or lags the network by more than the coin's allowed blocks. network_: the scanner knows no network height or wallet height, so the lag cannot be judged. not_: the coin is switched on but its backend is not configured (its chain source, or for TAO, Bitcoin, ETH and SOL the key that makes their deposit addresses). address_: no free receive address is ready. rates_: its rate sources were asked lately and left fewer than two fresh answers that agree. A UI shows any value as temporarily unavailable.
The assets that are on but whose quotes the server refuses for now, each with available false and its unavailable_, for a page that shows them as temporarily unavailable. Never offered. Empty when there is none; absent from older servers.
A coin a crypto invoice is paid in: usdc_solana (USDC on Solana), zec (Zcash, shielded), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) or sol (native SOL). TAO, Bitcoin, ETH and SOL are received into a Coinbase deposit address of each invoice's own and credited from the chain.
the chain to send on; absent from older servers
The chain a coin is paid on: solana (usdc_solana and sol), zcash, monero, bittensor (tao, the Finney network), bitcoin and ethereum (eth, Ethereum mainnet only). A coin sent on another network is not credited.
The decimals of the coin's atomic unit: amount_ is amount × 10^decimals (6 for USDC, 8 for Zcash and Bitcoin, 9 for TAO and SOL, 12 for Monero, 18 for ETH). Absent from older servers.
the most decimals a quoted amount has (8 for btc, 6 for every other coin); absent from older servers
Whether the coin's invoices carry a payment uri: false for tao, which has no payment link standard (the invoice gives the address and the amount, and uri_note says so). Absent from older servers.
the plans the asset sells (yearly, yearly_); never monthly
the data packs the asset sells (data_1tib, data_10tib); never data_256gib, which is sold only over x402 and with Gamma
the confirmations a payment needs before it is credited (for TAO, ETH and SOL, 1 is a finalized block)
how long a quote holds, in seconds
Whether the asset can be paid with now: true for every asset of assets and of crypto_, false for one of unavailable_ and crypto_. Absent from older servers, which listed only assets they would sell.
Why an asset that is on cannot be paid with now; absent when it can. scanner_: its scanner has not succeeded within three scan intervals (or never), or lags the network by more than the coin's allowed blocks. network_: the scanner knows no network height or wallet height, so the lag cannot be judged. not_: the coin is switched on but its backend is not configured (its chain source, or for TAO, Bitcoin, ETH and SOL the key that makes their deposit addresses). address_: no free receive address is ready. rates_: its rate sources were asked lately and left fewer than two fresh answers that agree. A UI shows any value as temporarily unavailable.
What a plan or a data pack costs in a coin now, without making an invoice: an agent or a script compares coins with it before it pays. No receive address is drawn and nothing is written. The invoice (/pay/crypto/intent or /pay/data/crypto-intent) quotes again when it is made, by the same rules, so the amount the invoice gives is the one to pay.
Give exactly one of plan and item_id. The bearer token is optional: with one, a plan is priced at the network's tier, and the welcome offer (yearly_) is quoted when the network may redeem it; without one, a plan is priced at the caller's tier and yearly_ is refused (offer_).
amount is the price × (1 + the coin's buffer: 1% for TAO, 0.5% for the others) ÷ rate_usd, rounded up to quote_, with amount_ its twin in the coin's atomic unit. A USDC invoice adds a unique sub-cent suffix to the price, so a USDC quote is the price alone, at rate_usd 1.
A refusal returns error with a 200 and a stable error.code (PurchaseError): invalid_ (an unknown asset, or not exactly one of plan and item_id), asset_ (the coin is off, not configured, or cannot be quoted right now), plan_, item_ (also a price over the per-invoice cap) or offer_. Per-ip rate limited.
A coin a crypto invoice is paid in: usdc_solana (USDC on Solana), zec (Zcash, shielded), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) or sol (native SOL). TAO, Bitcoin, ETH and SOL are received into a Coinbase deposit address of each invoice's own and credited from the chain.
The plan, when pricing Pro: yearly, or yearly_ for the welcome offer (with a bearer token of a network that may redeem it). Give exactly one of plan and item_id. monthly is card only and is refused (plan_).
The data pack, when pricing data.
ISO 3166-1 storefront country, when the caller knows it; the server resolves the regional tier otherwise
the coin (CryptoAsset)
the plan priced; empty for a data pack
the data pack priced; empty for a plan
the regional price tier of a plan's price; empty for a data pack
the welcome offer's price was applied
the price in USD, the same as the card price
the regular price (the full-year price for yearly_)
the coin's USD rate the amount is quoted at (1 for USDC)
What an invoice made now asks, an exact decimal in the coin: the price × (1 + the coin's buffer: 1% for TAO, 0.5% for the others) ÷ rate_usd, rounded up to quote_. A USDC invoice adds a unique sub-cent suffix to this price.
the same amount in the coin's atomic unit, a decimal integer string
the chain the payment is sent on (CryptoNetwork)
the decimals of the coin's atomic unit
the most decimals a quoted amount has
whether the coin's invoices carry a payment uri (false for tao)
how long an invoice's quote holds, in seconds
the confirmations a payment needs before it is credited
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
Start an invoice for Pro or a data pack, paid in an enabled asset (usdc_solana, zec, xmr, tao, btc, eth or sol), for the signed-in network (delivery account). Give exactly one of plan and item_id. The price is the card price at the caller's regional tier, from storefront_ when the app knows it; it is quoted by the server and never taken from the client. The bearer token is the API's normal one: an app's client token, or an agent's or a script's.
Each invoice has its own receive address (address), except USDC, which pays the one merchant address with a unique amount and a reference, and an exact amount in the coin, good until expires_at. Every coin but USDC is quoted from at least two rate sources that agree. Send exactly amount (every decimal) to address on network; network_ says what is not credited (a coin sent on another network, or a token instead of the coin). The address alone identifies the invoice for every coin but USDC; memo is the Solana Pay reference for usdc_solana (a USDC transfer sent by hand carries it as its memo) and empty for every other coin, sol included: a SOL invoice's own deposit address identifies it, and its Solana Pay reference is in uri only. Show a memo only when it is not empty.
uri is the payment link to show as a QR code and open in a wallet: solana: (Solana Pay; USDC names the USDC mint as its one spl-token, SOL names none), zcash: (ZIP 321), monero:, bitcoin: (BIP 21, with amount, label and message only) and ethereum: (EIP 681, Ethereum mainnet). TAO has no payment link standard: its uri is empty and uri_note says so; send the amount to the address by hand. A client never builds a payment uri of its own, and refuses to show one that does not pay address byte for byte.
status_token is a bearer secret for this one invoice, for /pay/crypto/status and /pay/crypto/requote. Keep it in memory, in device storage, in a POST body or in a url fragment, never in a query string or a log.
An open invoice of this network for the same asset and item (unpaid, unexpired, nothing in review) is returned again instead of a new one: the same address and the same quote, with a new status_token (every token handed out stays valid).
A refusal returns error with a 200 and a stable error.code (PurchaseError): invalid_ (an unknown asset, or not exactly one of plan and item_id), asset_ (the asset is off or not configured, or cannot be quoted right now), plan_ (a plan the asset does not sell, monthly included), item_, guest_ (plans only), offer_ (yearly_ without a redeemable welcome offer), rate_limited (too many invoices from this network this minute) or start_failed.
A coin a crypto invoice is paid in: usdc_solana (USDC on Solana), zec (Zcash, shielded), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) or sol (native SOL). TAO, Bitcoin, ETH and SOL are received into a Coinbase deposit address of each invoice's own and credited from the chain.
The plan, when buying Pro: yearly, or yearly_ for the welcome offer. Give exactly one of plan and item_id. monthly is card only and is refused (plan_).
The data pack, when buying data.
ISO 3166-1 storefront country, when the app knows it; the server resolves the regional tier otherwise
The bearer secret for this invoice's status and requote. Keep it in memory, in device storage, in a POST body or in a url fragment, never in a query string or a log. An open invoice returned again comes with a new token; every token handed out stays valid.
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the resolved network name, as stored, for delivery network
the regional price tier of a plan's price; empty for a data pack
the welcome offer's price was applied
the price in USD, the same as the card price
the regular price (the full-year price for yearly_)
the coin's USD rate the amount was quoted at (1 for USDC)
Where to pay: the invoice's own receive address (a Zcash unified address, a Monero subaddress, or a Coinbase deposit address for TAO, Bitcoin, ETH and SOL, ETH's in EIP-55 case), or for USDC the one merchant address.
The exact amount to send, a decimal string in the coin. Amounts are rounded up to the coin's quote decimals (8 for Bitcoin, 6 for the others); a USDC amount carries its unique 6-decimal suffix, so show and pay every decimal.
the same amount in atomic units (piconero, zatoshi, millionths of a USDC, rao, satoshi, wei or lamport), a decimal integer string
For usdc_solana, the Solana Pay reference: the memo of a USDC transfer sent by hand. Empty for every other coin, sol included (its own deposit address identifies the invoice; its Solana Pay reference is in uri only). Show a memo only when it is not empty.
The payment uri the server built, to show as a QR code and open in a wallet: solana: (Solana Pay; USDC with the USDC mint as its one spl-token, SOL with none), zcash: (ZIP 321), monero:, bitcoin: (BIP 21, amount, label and message only) or ethereum: (EIP 681). Empty for tao, which has no payment link standard (uri_note). A client never builds its own, and refuses one that does not pay address byte for byte.
when uri is empty, why, in English (TAO has no payment link standard); else empty
the chain the payment must be sent on (CryptoNetwork)
What to send and on which network, in English, for a person or an agent paying by hand: a coin sent on another network, or a token instead of the coin, is not credited.
when the quote ends
the invoice's state now, as /pay/crypto/status returns it
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the network that receives the data, for delivery network
A crypto invoice's state; /pay/crypto/status says when each applies.
Why the invoice is in review: underpaid, late_, extra, orphaned, voided, credit_, screening, transfer_ or amount_ (/pay/crypto/status says when each applies). Empty otherwise. A UI shows the review copy for any value, a new one included.
the quoted amount, an exact decimal in the coin
the quoted amount in atomic units, a decimal integer
what has arrived so far, mempool included, top-ups to the same address counted
how much more to send to the same address; "0" once the amount is covered
What arrived beyond amount, "0" when nothing did. An overpaid invoice is credited as paid; the surplus is returned on request to support, in the same coin. Absent from older servers.
the chain the payment is sent on (CryptoNetwork); absent from older servers
The lowest confirmation count among the payments that make up the amount (0 in the mempool). Blocks for Bitcoin, Zcash and Monero; for TAO, ETH and SOL, 1 once the payment's block is finalized.
when the quote ends; null for unknown
the balance code a paid invoice bought, for delivery code; empty for a gift order, whose codes are on its cards
quote_ while expired, and underpaid while in review for a short payment; absent otherwise.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
Start an invoice for a data pack without signing in (the ur.io buy-data page, or an agent or a script), paid in an enabled asset. Data packs only: a plan is refused with invalid_.
With network_name, the data goes to that network (delivery network), matched like /pay/data/network-lookup; no such network is refused with error.code network_. An open invoice for the same network, asset and item is returned as it is.
Without network_name, the payment buys a balance code (delivery code). /pay/crypto/status shows the code as balance_code once the invoice is paid, and it is emailed too when email is given. An email that does not look like one is refused with invalid_. Each request is a new invoice, and an asset that does not deliver codes, or has its most open code invoices, refuses it with asset_.
Otherwise the rules and the result are those of /pay/crypto/intent. Unauthenticated, per-ip rate limited (rate_limited).
A coin a crypto invoice is paid in: usdc_solana (USDC on Solana), zec (Zcash, shielded), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) or sol (native SOL). TAO, Bitcoin, ETH and SOL are received into a Coinbase deposit address of each invoice's own and credited from the chain.
the network that receives the data; empty buys a balance code
where to email the balance code too (delivery code only); optional
The bearer secret for this invoice's status and requote. Keep it in memory, in device storage, in a POST body or in a url fragment, never in a query string or a log. An open invoice returned again comes with a new token; every token handed out stays valid.
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the resolved network name, as stored, for delivery network
the regional price tier of a plan's price; empty for a data pack
the welcome offer's price was applied
the price in USD, the same as the card price
the regular price (the full-year price for yearly_)
the coin's USD rate the amount was quoted at (1 for USDC)
Where to pay: the invoice's own receive address (a Zcash unified address, a Monero subaddress, or a Coinbase deposit address for TAO, Bitcoin, ETH and SOL, ETH's in EIP-55 case), or for USDC the one merchant address.
The exact amount to send, a decimal string in the coin. Amounts are rounded up to the coin's quote decimals (8 for Bitcoin, 6 for the others); a USDC amount carries its unique 6-decimal suffix, so show and pay every decimal.
the same amount in atomic units (piconero, zatoshi, millionths of a USDC, rao, satoshi, wei or lamport), a decimal integer string
For usdc_solana, the Solana Pay reference: the memo of a USDC transfer sent by hand. Empty for every other coin, sol included (its own deposit address identifies the invoice; its Solana Pay reference is in uri only). Show a memo only when it is not empty.
The payment uri the server built, to show as a QR code and open in a wallet: solana: (Solana Pay; USDC with the USDC mint as its one spl-token, SOL with none), zcash: (ZIP 321), monero:, bitcoin: (BIP 21, amount, label and message only) or ethereum: (EIP 681). Empty for tao, which has no payment link standard (uri_note). A client never builds its own, and refuses one that does not pay address byte for byte.
when uri is empty, why, in English (TAO has no payment link standard); else empty
the chain the payment must be sent on (CryptoNetwork)
What to send and on which network, in English, for a person or an agent paying by hand: a coin sent on another network, or a token instead of the coin, is not credited.
when the quote ends
the invoice's state now, as /pay/crypto/status returns it
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the network that receives the data, for delivery network
A crypto invoice's state; /pay/crypto/status says when each applies.
Why the invoice is in review: underpaid, late_, extra, orphaned, voided, credit_, screening, transfer_ or amount_ (/pay/crypto/status says when each applies). Empty otherwise. A UI shows the review copy for any value, a new one included.
the quoted amount, an exact decimal in the coin
the quoted amount in atomic units, a decimal integer
what has arrived so far, mempool included, top-ups to the same address counted
how much more to send to the same address; "0" once the amount is covered
What arrived beyond amount, "0" when nothing did. An overpaid invoice is credited as paid; the surplus is returned on request to support, in the same coin. Absent from older servers.
the chain the payment is sent on (CryptoNetwork); absent from older servers
The lowest confirmation count among the payments that make up the amount (0 in the mempool). Blocks for Bitcoin, Zcash and Monero; for TAO, ETH and SOL, 1 once the payment's block is finalized.
when the quote ends; null for unknown
the balance code a paid invoice bought, for delivery code; empty for a gift order, whose codes are on its cards
quote_ while expired, and underpaid while in review for a short payment; absent otherwise.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
The state of an invoice started with /pay/crypto/intent or /pay/data/crypto-intent, read with its status_token, for a client, an agent or a script to poll until it is paid (every 5 to 10 seconds while it waits; past 60 a minute from one address the answer is a 429, and the last state stands). status, first match wins:
unknown: no such invoice, or the token does not match. Nothing else is filled in.paid: credited. balance_code is set for delivery code. An overpayment is credited too, with what arrived beyond the amount in excess; the surplus is returned on request to support, in the same coin, to an address the customer gives. A credited invoice that later receives a second payment stays paid.review: a payment needs an operator. review_ reason says why: underpaid (short at expiry), late_ underpaid (arrived after expiry, worth less than the price at the rate of when it was first seen), extra (a second payment to a paid invoice), orphaned (a credited payment left the chain and its entitlement was ended; reported although the invoice was credited), voided (a payment to an invoice an operator closed), credit_ failed (the payment is there but its credit kept failing), screening (the payment's senders are being checked against the sanctions list before credit; it is credited once the check passes or an operator decides), transfer_ shape (a TAO transfer of a kind the rail does not credit by itself: a batch, a proxy or multisig call, an EVM precompile send, a stake transfer) or amount_ unmatched (a payment to a coin's shared deposit address whose amount is no open invoice's). error.code is underpaid for the first two. A UI shows the review copy for any value.confirming: at least 99.5% of amount arrived (or, after expiry, a late payment worth the price at the rate of when it was first seen), with fewer than confirmations_ required confirmations.seen: something arrived, but less than that; remaining is how much more to send to the same address, before expires_at. A top-up to the same address counts toward the invoice.expired: past expires_at with nothing received. error.code is quote_ expired, and /pay/crypto/requote gives a new quote.pending: nothing received yet.received counts payments in the mempool and on chain; confirmations is the lowest among the payments that make up the amount (0 in the mempool). It counts blocks for Bitcoin (credited at 1), Zcash (10) and Monero (1); for TAO, ETH and SOL it is 1 once the payment's block is finalized and 0 before (ETH finalizes in about 15 minutes, TAO in about half a minute). usdc_solana only reports pending, paid or expired. A late payment that covers the price at the rate of when it was first seen is still credited. Amounts are exact decimal strings in the coin, each beside its atomic twin (piconero, zatoshi, millionths of a USDC, rao, satoshi, wei or lamport). Unauthenticated, per-ip rate limited.
the invoice's bearer secret, from its intent
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the network that receives the data, for delivery network
A crypto invoice's state; /pay/crypto/status says when each applies.
Why the invoice is in review: underpaid, late_, extra, orphaned, voided, credit_, screening, transfer_ or amount_ (/pay/crypto/status says when each applies). Empty otherwise. A UI shows the review copy for any value, a new one included.
the quoted amount, an exact decimal in the coin
the quoted amount in atomic units, a decimal integer
what has arrived so far, mempool included, top-ups to the same address counted
how much more to send to the same address; "0" once the amount is covered
What arrived beyond amount, "0" when nothing did. An overpaid invoice is credited as paid; the surplus is returned on request to support, in the same coin. Absent from older servers.
the chain the payment is sent on (CryptoNetwork); absent from older servers
The lowest confirmation count among the payments that make up the amount (0 in the mempool). Blocks for Bitcoin, Zcash and Monero; for TAO, ETH and SOL, 1 once the payment's block is finalized.
when the quote ends; null for unknown
the balance code a paid invoice bought, for delivery code; empty for a gift order, whose codes are on its cards
quote_ while expired, and underpaid while in review for a short payment; absent otherwise.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
A new quote for an invoice that nothing has been paid to (pending or expired), read with its status_token. For every coin but USDC it is a new rate, amount and expiry for the same address; the old quote is kept in the invoice's history. A usdc_solana amount is already in dollars, so its quote only gets a later expires_at. The result is the invoice, as /pay/crypto/intent returns it, with the caller's own status_token.
Refused with invalid_ once something was received, or for an unknown invoice or token or a closed one, and with asset_ when the asset is off or cannot be quoted right now. Unauthenticated, per-ip rate limited (rate_limited).
the invoice's bearer secret, from its intent
The bearer secret for this invoice's status and requote. Keep it in memory, in device storage, in a POST body or in a url fragment, never in a query string or a log. An open invoice returned again comes with a new token; every token handed out stays valid.
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the resolved network name, as stored, for delivery network
the regional price tier of a plan's price; empty for a data pack
the welcome offer's price was applied
the price in USD, the same as the card price
the regular price (the full-year price for yearly_)
the coin's USD rate the amount was quoted at (1 for USDC)
Where to pay: the invoice's own receive address (a Zcash unified address, a Monero subaddress, or a Coinbase deposit address for TAO, Bitcoin, ETH and SOL, ETH's in EIP-55 case), or for USDC the one merchant address.
The exact amount to send, a decimal string in the coin. Amounts are rounded up to the coin's quote decimals (8 for Bitcoin, 6 for the others); a USDC amount carries its unique 6-decimal suffix, so show and pay every decimal.
the same amount in atomic units (piconero, zatoshi, millionths of a USDC, rao, satoshi, wei or lamport), a decimal integer string
For usdc_solana, the Solana Pay reference: the memo of a USDC transfer sent by hand. Empty for every other coin, sol included (its own deposit address identifies the invoice; its Solana Pay reference is in uri only). Show a memo only when it is not empty.
The payment uri the server built, to show as a QR code and open in a wallet: solana: (Solana Pay; USDC with the USDC mint as its one spl-token, SOL with none), zcash: (ZIP 321), monero:, bitcoin: (BIP 21, amount, label and message only) or ethereum: (EIP 681). Empty for tao, which has no payment link standard (uri_note). A client never builds its own, and refuses one that does not pay address byte for byte.
when uri is empty, why, in English (TAO has no payment link standard); else empty
the chain the payment must be sent on (CryptoNetwork)
What to send and on which network, in English, for a person or an agent paying by hand: a coin sent on another network, or a token instead of the coin, is not credited.
when the quote ends
the invoice's state now, as /pay/crypto/status returns it
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the network that receives the data, for delivery network
A crypto invoice's state; /pay/crypto/status says when each applies.
Why the invoice is in review: underpaid, late_, extra, orphaned, voided, credit_, screening, transfer_ or amount_ (/pay/crypto/status says when each applies). Empty otherwise. A UI shows the review copy for any value, a new one included.
the quoted amount, an exact decimal in the coin
the quoted amount in atomic units, a decimal integer
what has arrived so far, mempool included, top-ups to the same address counted
how much more to send to the same address; "0" once the amount is covered
What arrived beyond amount, "0" when nothing did. An overpaid invoice is credited as paid; the surplus is returned on request to support, in the same coin. Absent from older servers.
the chain the payment is sent on (CryptoNetwork); absent from older servers
The lowest confirmation count among the payments that make up the amount (0 in the mempool). Blocks for Bitcoin, Zcash and Monero; for TAO, ETH and SOL, 1 once the payment's block is finalized.
when the quote ends; null for unknown
the balance code a paid invoice bought, for delivery code; empty for a gift order, whose codes are on its cards
quote_ while expired, and underpaid while in review for a short payment; absent otherwise.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
What gift codes sell for now, for the gift dialog. A gift code grants a year of Pro (pro_days) from when it is redeemed, queued after the recipient's paid Pro period, and can be redeemed for redeemable_ after purchase. It redeems like any balance code: /subscription/redeem-balance-code, or balance_code when a network is created.
The unit price depends on how many gifts the order has: the tier with the highest min_quantity not over the quantity prices every gift in the order. Prices are integer cents in currency, one price worldwide (no regional tiers). An order takes 1 to max_quantity gifts. crypto_ are the coins /pay/gift/crypto-intent takes. gamma_ says whether /pay/gift/gamma-intent can take an order now: Gamma purchases are available (/pay/gamma/terms available) and the cap of a gift paid in a coin or with Gamma is set.
While enabled is false, gift codes are not on sale: /pay/gift/checkout, /pay/gift/crypto-intent and /pay/gift/gamma-intent refuse with gift_. Unauthenticated.
gift codes are on sale; while false, /pay/gift/checkout and /pay/gift/crypto-intent refuse with gift_
the season the gift dialog and the cards are dressed for, such as winter-2026
the currency of every price, usd
the most gifts one order takes
The unit price by quantity: the tier with the highest min_quantity not over an order's quantity prices every gift in the order.
the price of each gift in an order of at least min_quantity gifts, in cents
the days of Pro a gift code grants, from when it is redeemed
how many days after purchase a gift code can be redeemed
the coins a gift order can be paid in (CryptoAsset), with /pay/gift/crypto-intent
A gift order can be paid with Gamma now, with /pay/gift/gamma-intent: gift codes are on sale, Gamma purchases are available (/pay/gamma/terms available), and the cap of a gift order paid in a coin or with Gamma is set. Absent from older servers, which read as false.
Buy gift codes by card: makes the order and starts its Stripe checkout for quantity gifts at the order's unit price (/pay/gift/config). ui_mode embedded returns client_ and publishable_ for a checkout inside the gift dialog; hosted returns url, the checkout page, which comes back to https:// once paid (the token is not in it) and to https:// when cancelled.
Once paid, the order makes quantity codes and renders a card for each. email gets every card in one PDF. With delivery them, each address in recipients (exactly quantity, in order) also gets an email with its own card and the note, from URnetwork with email as its reply-to, on send_on at 09:00 in timezone, or right after payment without send_on. Paid by card, these emails never go out before two hours after the payment, past the early fraud warnings; a refund or a dispute in that time withdraws them. /pay/gift/order answers when they go out (friends_). The cards and the emails are in language.
With a signed-in session, referral_ links the codes to the caller's network: whoever redeems one and has no referrer yet becomes the network's referral, within the referral cap. It is ignored without a session.
order_id and order_token read the order (/pay/gift/order) and download its cards (/pay/gift/cards.pdf). The token is a bearer secret for this one order: both take it in a POST body, so it never appears in a URL.
A refusal returns error with a 200 and a stable error.code (PurchaseError): gift_, invalid_, invalid_, invalid_, invalid_, message_, gift_ (the note or the signature holds a link) or gift_ (with this order's recipients, the buyer's email would pass 20 friend emails in 24 hours; delivery me has no daily limit), or a shared one: invalid_ (an unknown delivery, language or ui mode), rate_limited (too many checkouts from this address this minute), checkout_ or start_failed.
how many gifts, from 1 to max_quantity (/pay/gift/config)
me: every card goes to email. them: each address in recipients also gets its own card, on send_on.
The buyer's email. It gets every card in one PDF (the receipt, with delivery them), and is the reply-to of the friend emails.
delivery them, exactly quantity email addresses, a card each, in order
Delivery them: the buyer's local date to send the friend emails on, at 09:00 in timezone. Omitted, they are sent right after payment.
the buyer's IANA time zone, such as America/, so send_on means 09:00 their time
the note on the cards and in the friend emails
the signature under the note
the language of the cards and the emails
With a signed-in session, link the codes to the caller's network for referral credit. Ignored without a session.
embedded returns client_ and publishable_ for a checkout inside the gift dialog; hosted returns url, the checkout page.
the bearer secret for this one order, for /pay/gift/order and /pay/gift/cards.pdf; send it in a POST body, never in a URL
the order's total, quantity gifts at the unit price, in cents
for ui_mode embedded, the Stripe checkout session's client secret
for ui_mode embedded, the Stripe publishable key to mount the checkout with
for ui_mode hosted, the checkout page to send the buyer to
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
Buy gift codes in a coin: makes the order and a crypto invoice for its total, at most $500, the cap of a gift order paid in a coin or with Gamma (an order of 20 at $23.99 is $479.80). The request is that of /pay/gift/checkout without ui_mode, plus asset and bittensor_, which adds a "Made with Bittensor" line to the cards and the friend emails. The result is the invoice, as /pay/crypto/intent returns it, to pay and to follow with /pay/crypto/status the same way, plus the order's order_id and order_token and bittensor_ as given. Once the invoice is paid, the order is fulfilled as a card order is, except that a coin payment has no hold: the friend emails go out on send_on at 09:00 in timezone, or right after payment.
The invoice's item_id is gift_ and its delivery is code, and each order has an invoice of its own. Its status never shows a code (balance_code stays empty): the order's cards carry them (/pay/gift/cards.pdf).
A refusal returns error with a 200 and a stable error.code (PurchaseError): gift_ and the order's own, as /pay/gift/checkout answers them (invalid_, invalid_, invalid_, invalid_, message_, gift_, gift_), or the invoice's, as /pay/crypto/intent answers them: invalid_ (an unknown asset, delivery or language), asset_, item_ (gift orders cannot be paid in a coin now), rate_limited or start_failed.
how many gifts, from 1 to max_quantity (/pay/gift/config)
me: every card goes to email. them: each address in recipients also gets its own card, on send_on.
The buyer's email. It gets every card in one PDF (the receipt, with delivery them), and is the reply-to of the friend emails.
delivery them, exactly quantity email addresses, a card each, in order
Delivery them: the buyer's local date to send the friend emails on, at 09:00 in timezone. Omitted, they are sent right after payment.
the buyer's IANA time zone, such as America/, so send_on means 09:00 their time
the note on the cards and in the friend emails
the signature under the note
the language of the cards and the emails
With a signed-in session, link the codes to the caller's network for referral credit. Ignored without a session.
A coin a crypto invoice is paid in: usdc_solana (USDC on Solana), zec (Zcash, shielded), xmr (Monero), tao (TAO on Bittensor), btc (Bitcoin), eth (ETH on Ethereum mainnet) or sol (native SOL). TAO, Bitcoin, ETH and SOL are received into a Coinbase deposit address of each invoice's own and credited from the chain.
add a "Made with Bittensor" line to the cards and the friend emails
The bearer secret for this invoice's status and requote. Keep it in memory, in device storage, in a POST body or in a url fragment, never in a query string or a log. An open invoice returned again comes with a new token; every token handed out stays valid.
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the resolved network name, as stored, for delivery network
the regional price tier of a plan's price; empty for a data pack
the welcome offer's price was applied
the price in USD, the same as the card price
the regular price (the full-year price for yearly_)
the coin's USD rate the amount was quoted at (1 for USDC)
Where to pay: the invoice's own receive address (a Zcash unified address, a Monero subaddress, or a Coinbase deposit address for TAO, Bitcoin, ETH and SOL, ETH's in EIP-55 case), or for USDC the one merchant address.
The exact amount to send, a decimal string in the coin. Amounts are rounded up to the coin's quote decimals (8 for Bitcoin, 6 for the others); a USDC amount carries its unique 6-decimal suffix, so show and pay every decimal.
the same amount in atomic units (piconero, zatoshi, millionths of a USDC, rao, satoshi, wei or lamport), a decimal integer string
For usdc_solana, the Solana Pay reference: the memo of a USDC transfer sent by hand. Empty for every other coin, sol included (its own deposit address identifies the invoice; its Solana Pay reference is in uri only). Show a memo only when it is not empty.
The payment uri the server built, to show as a QR code and open in a wallet: solana: (Solana Pay; USDC with the USDC mint as its one spl-token, SOL with none), zcash: (ZIP 321), monero:, bitcoin: (BIP 21, amount, label and message only) or ethereum: (EIP 681). Empty for tao, which has no payment link standard (uri_note). A client never builds its own, and refuses one that does not pay address byte for byte.
when uri is empty, why, in English (TAO has no payment link standard); else empty
the chain the payment must be sent on (CryptoNetwork)
What to send and on which network, in English, for a person or an agent paying by hand: a coin sent on another network, or a token instead of the coin, is not credited.
when the quote ends
the invoice's state now, as /pay/crypto/status returns it
the coin (CryptoAsset)
the plan the invoice buys; empty for a data pack
the data pack the invoice buys, or gift_ for a gift order's codes (/pay/gift/crypto-intent); empty for a plan
Where the paid invoice goes: account (the signed-in network), network (a network named on the buy-data page) or code (a balance code, shown once paid and emailed when an address was given).
the network that receives the data, for delivery network
A crypto invoice's state; /pay/crypto/status says when each applies.
Why the invoice is in review: underpaid, late_, extra, orphaned, voided, credit_, screening, transfer_ or amount_ (/pay/crypto/status says when each applies). Empty otherwise. A UI shows the review copy for any value, a new one included.
the quoted amount, an exact decimal in the coin
the quoted amount in atomic units, a decimal integer
what has arrived so far, mempool included, top-ups to the same address counted
how much more to send to the same address; "0" once the amount is covered
What arrived beyond amount, "0" when nothing did. An overpaid invoice is credited as paid; the surplus is returned on request to support, in the same coin. Absent from older servers.
the chain the payment is sent on (CryptoNetwork); absent from older servers
The lowest confirmation count among the payments that make up the amount (0 in the mempool). Blocks for Bitcoin, Zcash and Monero; for TAO, ETH and SOL, 1 once the payment's block is finalized.
when the quote ends; null for unknown
the balance code a paid invoice bought, for delivery code; empty for a gift order, whose codes are on its cards
quote_ while expired, and underpaid while in review for a short payment; absent otherwise.
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
the bearer secret for this one order, for /pay/gift/order and /pay/gift/cards.pdf; send it in a POST body, never in a URL
the request's bittensor_
Buy gift codes with Gamma: makes the order and a Gamma purchase for its total, paid from the signed-in account's SN25 gamma deposit, exactly as /pay/gamma/intent sells a plan or a data pack. It takes the same bearer (a network JWT or an API key), and a guest account may buy, since the codes are the delivery. The request is that of /pay/gift/crypto-intent without asset: the order's fields, and bittensor_, which adds a "Made with Bittensor" line to the cards and the friend emails; plus coldkey, as /pay/gamma/intent takes it, when a mint failed with NonAssociatedColdKey.
The purchase is priced at the order's total by the gift's quantity tiers (/pay/gift/config), one gamma per US dollar, with no price tier and no welcome offer, and at most $500, the cap of a gift order paid in a coin or with Gamma (an order of 20 at $23.99 is $479.80). The answer is the purchase, with every field /pay/gamma/intent answers: deposit_, amount_gamma, reference, min_, indicative_, status_token and the two mint commands, with item_id gift_ and delivery code; plus the order's order_id and order_token and bittensor_ as given. Each order has a purchase of its own: an open one is never returned again. A gift starts no automatic charge, so automatic_ is empty and auto_ is min_.
A gift's purchase is open for two hours (expires_at), or for the shorter life of every Gamma purchase when that is less; a plan or a data pack stays open longer. Every purchase of an account draws on its one deposit hotkey, and the oldest open one is charged first, so a gift left behind must not be charged when the deposit is later filled for something else. An expired purchase is never charged, and its gamma stays in the deposit; the price is in US dollars, so starting again costs the same.
An account has one open gift purchase at a time, since every one draws on its one deposit hotkey: a new gift purchase voids the account's other open gift purchases (never a plan or a data purchase), so a gift that was changed or left can never be charged. A voided purchase reads review with review_ voided on /pay/gamma/status, and its order stays pending and no longer counts toward the daily friend emails. While an earlier gift's spend is in flight (sent to the chain, or landed and being credited), a new gift purchase is refused with payment_. /pay/gift/gamma-cancel voids an order's purchase, for paying another way.
Mint into deposit_ as /pay/gamma/intent explains, follow the purchase with /pay/gamma/status and its status_token, and the order with /pay/gift/order and its order_token. Once our spend of amount_gamma is finalized, the order is paid and fulfilled as a card order is: its codes, its cards (/pay/gift/cards.pdf) and its emails. As for a coin, there is no hold: the friend emails go out on send_on at 09:00 in timezone, or right after payment (/pay/gift/order friends_). The purchase's status never shows a code (balance_code stays empty): the order's cards carry them. Buying a gift turns on no automatic renewal or top-up and sends no Gamma receipt; the order's own email to email is the receipt.
Gamma can't be refunded, so a gift order paid with Gamma is final sale: no refund or dispute voids its codes.
A refusal returns error with a 200 and a stable error.code (GammaPaymentError): gift_ and the order's own, as /pay/gift/checkout answers them (invalid_, invalid_, invalid_, invalid_, message_, gift_, gift_), or the purchase's, as /pay/gamma/intent answers them: invalid_ (an unknown delivery or language, or a coldkey that is not an SS58 address), asset_ (Gamma purchases are off, or minting is off while the deposit cannot already pay: mint_ says why), item_ (gift orders cannot be paid with Gamma now, or the order is over the cap), deposit_ (every hotkey of the account belongs to another coldkey; ask again with coldkey), rate_limited (too many attempts from this address or this account, or too many open Gamma purchases), payment_ (an earlier gift's Gamma payment is still being processed; try again in a few minutes) or start_failed.
how many gifts, from 1 to max_quantity (/pay/gift/config)
me: every card goes to email. them: each address in recipients also gets its own card, on send_on.
The buyer's email. It gets every card in one PDF (the receipt, with delivery them), and is the reply-to of the friend emails.
delivery them, exactly quantity email addresses, a card each, in order
Delivery them: the buyer's local date to send the friend emails on, at 09:00 in timezone. Omitted, they are sent right after payment.
the buyer's IANA time zone, such as America/, so send_on means 09:00 their time
the note on the cards and in the friend emails
the signature under the note
the language of the cards and the emails
With a signed-in session, link the codes to the caller's network for referral credit. Ignored without a session.
add a "Made with Bittensor" line to the cards and the friend emails
The SS58 coldkey that will mint, as /pay/gamma/intent takes it: to get a deposit hotkey whose deposit that coldkey can open or already owns, after a mint failed with NonAssociatedColdKey.
The purchase's bearer secret, for /pay/gamma/status.
The data pack, or gift_ for a gift order's codes (/pay/gift/gamma-intent); "" for a plan.
account or code; a gift order's is code.
The price in gamma, exactly what our spend takes.
The purchase's public 32-byte spend reference (0x hex), carried by our GammaSpent.
The SS58 hotkey to mint into. Not a pay-to address; never send TAO to it.
About the TAO that mints what the deposit still needs (at least 0.1 gamma); "" while minting is off.
With review: voided or credit_; else "".
The deposit's balance as last seen; "" when there is no deposit.
The balance within what the daily cap allows now; "" when there is no deposit.
How much more gamma the deposit needs for the price.
The deposit's daily spend cap; "" for none.
The finalized block of our GammaSpent.
A paid data pack's code, for delivery code; always "" for a gift order (/pay/gift/gamma-intent), whose codes are on its cards.
Plain TAO sent to the deposit hotkey by mistake, in rao.
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
The PurchaseError codes invalid_, asset_, plan_, item_, offer_, guest_, invalid_, rate_limited, start_failed and quote_; already_: a plan (or Gamma renewal) refused, or a plan's status covered, because another payment pays for or bills the same days (another Pro subscription that renews, or another Gamma payment for the network's Pro plan); and Gamma's own: insufficient_: the deposit holds, or held when we spent, less gamma than the price. daily_: the deposit's daily spend cap did not allow the price when we spent. daily_: the deposit's daily spend cap is below the price, so no spend can pass; raise it to min_. wrong_: the deposit names another spender. no_deposit: there was no deposit at the hotkey when we spent. invalid_: the chain refused the amount. deposit_: the hotkey's deposit, or the hotkey, belongs to another coldkey (the chain's NonAssociatedColdKey); ask again with coldkey. The mint failures a client sees from btcli map to: AmountTooLow (a mint below 0.1 gamma) to mint_, InsufficientLiquidity (a mint above the pool's swap input limit) to mint_, SlippageTooHigh (less than the mint's minimum) to mint_, TaoUsdPriceUnavailable and GammaDisabled to asset_. /pay/gift/gamma-intent only, a gift order refused, as PurchaseError describes each: gift_, invalid_, invalid_, invalid_, message_, gift_, gift_, and payment_ (an earlier gift's Gamma payment is still being processed).
the bearer secret for this one order, for /pay/gift/order and /pay/gift/cards.pdf; send it in a POST body, never in a URL
the request's bittensor_
Cancel a gift order's Gamma purchase, to pay for the gifts another way: the purchase /pay/gift/gamma-intent made for the order is voided and can never be charged. The order is read with the order_id and order_token that /pay/gift/gamma-intent returned, sent as order_id and token in the body, as /pay/gift/order takes them; no sign-in. The order stays pending, and no longer counts toward the daily friend emails.
cancelled is true once the order's purchase is voided: now, before (by a newer gift purchase, or an earlier cancel, so a repeated cancel answers the same), or when the order has no purchase left that could be charged. status is the order's, as /pay/gift/order answers it.
cancelled false, error.code payment_ in_ progress. Check the order again in a few minutes.cancelled false, status paid, no error.order_id and token that open no order: error.code invalid_ request, and status empty when no order matched.Unauthenticated, per-ip rate limited as /pay/gift/order is.
the order's order_token, from /pay/gift/checkout, /pay/gift/crypto-intent or /pay/gift/gamma-intent
the order's Gamma purchase is voided and can never be charged (now or before), or the order has none left that could be
the order's status, as /pay/gift/order answers it; a cancelled order stays pending; "" when no order matches the id and token
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
A gift order's state, read with the order_id and order_token that /pay/gift/checkout, /pay/gift/crypto-intent or /pay/gift/gamma-intent returned, sent as order_id and token in the body: pending until it is paid, then paid, or refunded after a refund, which voids its unredeemed codes. An order paid with Gamma is final sale and is never refunded; one whose Gamma purchase was voided (/pay/gift/gamma-cancel, or a newer gift purchase) stays pending. After payment the gift dialog polls it about every 2 seconds until pdf_ready, then downloads the cards from /pay/gift/cards.pdf.
An unknown order, a malformed order_id and a wrong token are all answered 404, so an answer says nothing about which orders exist. Unauthenticated, per-ip rate limited.
the order's order_token, from /pay/gift/checkout, /pay/gift/crypto-intent or /pay/gift/gamma-intent
delivery them, the buyer's local date the friend emails are sent on; absent when they go right after payment
when the friend emails go out (or went out), RFC 3339; send_on at 09:00 in the buyer's time zone, else right after payment, and paid by card never before two hours after the payment (paid in a coin or with Gamma, there is no hold). Null when no friend is emailed - delivery me, an order not paid yet, or a refunded one.
the buyer's email, masked, such as b•••@example.com
the cards are rendered, and /pay/gift/cards.pdf serves them
Every card of a paid gift order in one PDF, a card per page, read with the order's order_id and token in the body, as /pay/gift/order takes them, and answered as an attachment named URnetwork-gift-cards.pdf. The gift dialog fetches it as a Blob and saves it through an object URL, so the token never appears in a URL. Not found until the cards are rendered (poll /pay/gift/order until pdf_ready), for a refunded order, whose codes are void, and when no order matches the id and token. Unauthenticated, per-ip rate limited.
the order's order_token, from /pay/gift/checkout, /pay/gift/crypto-intent or /pay/gift/gamma-intent
Check a balance code without signing in, for the redeem page: what it grants (kind: data, or pro_gift for a gift code's year of Pro, pro_days), whether it can be redeemed (status) and until when (redeem_by). /subscription/check-balance-code is the signed-in check.
status is ok (it can be redeemed), redeemed, expired (past redeem_by), voided (refunded) or not_found, which carries nothing else. Unauthenticated, per-ip rate limited: too many checks from this address this minute return error.code rate_limited with a 200, and no status.
the code, 26 characters
what the code grants, data or pro_gift (a gift code, a year of Pro); absent for not_found
ok: it can be redeemed. redeemed, expired (past redeem_by), voided (refunded) or not_found: it cannot.
the days of Pro a gift code grants (365); 0 for a data code
the last time the code can be redeemed
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
Create a Stripe Checkout Session for a subscription or data pack.
ui_mode selects which shape the result carries -- a single Stripe session cannot produce both:
checkout_url, which the client opens in a browser.client_ secret and publishable_ key, which the client uses to mount Stripe Embedded Checkout inline (the desktop apps load ur.io/checkout in a webview with these).A Pro session carries the caller's regional tier price and applies a redeemable offer itself: the welcome offer's coupon on the yearly plan, or the caller's win-back offer (winback_ on /subscription/balance) on the monthly plan's first month. The win-back offer is a promotion code Stripe honors only for the customer it was made for, so that session is created for the caller's Stripe customer.
The subscription is granted by the invoice.paid webhook, never by the client; the client only polls /subscription/balance afterwards.
A legacy guest network (no sign-in method) is refused with error.code guest_ (PurchaseError). Every other refusal carries its own code too, for example already_, plan_ or start_failed.
pro_monthly, pro_yearly, or a data pack sold by card: data_1tib or data_10tib. The 256 GiB pack (data_256gib) is sold only over x402 and with Gamma, and is refused here with item_.
ISO 3166-1 storefront country, when the caller knows it. The Pro items are priced at the caller's regional tier and, when the welcome offer is redeemable (yearly only), the 25% coupon is applied server-side; the charged tier is finalized from the card's billing country once attached.
"hosted" (default) or "embedded".
"never" keeps an EMBEDDED checkout fully inline: Stripe fires the client's onComplete callback instead of redirecting, so the page the customer is on never navigates. Only valid with ui_mode "embedded". Empty means the embedded flow redirects to the configured return url, and hosted behaves as always.
which of the two shapes below is populated
hosted mode only
embedded mode only
embedded mode only
both modes; the caller can reconcile the purchase with this
A stable code for the refusal, so a client can pick a localized message or flow. One of: guest_: the network is a legacy guest network with no sign-in method, so nothing could sign back in to a plan bought on it. Add a sign-in method (POST /auth/add-auth) first; the apps open their add-sign-in sheet. Store-verified purchases and webhooks are never refused this way. already_: the network already has an active Pro subscription; nothing was charged. plan_: the plan cannot be sold now (no price or product is configured for it). item_: the data pack cannot be sold now. offer_: the welcome offer is not, or no longer, redeemable by this network. checkout_: this deployment has no checkout configured. invalid_: the request names an item, plan, provider, ui mode or reference the endpoint does not take (a client defect). invalid_: the email address the code goes to does not look like one. network_: a data purchase for a network by name came without the name. network_: no network has the given name. rate_limited: too many attempts from this address; try again in a minute. start_failed: the payment could not be started (Stripe or the database failed); a retry may work. asset_: the coin is switched off or not configured, or cannot be quoted right now (rates missing, stale or too far apart, the node or the scanner behind, no free receive address, too many open invoices), or does not deliver balance codes. The UI says it is temporarily unavailable. quote_: the quote's time ran out with nothing received; /pay/crypto/requote gives a new one. underpaid: the invoice ended short, and an operator reviews it. gift_: gift codes are not on sale now (/pay/gift/config enabled is false). invalid_: the number of gifts is not between 1 and the most one order takes (/pay/gift/config max_quantity). invalid_: delivery them needs exactly one recipient address per gift, each an email address. invalid_: send_on is not a date from tomorrow to a year out in the buyer's timezone, or comes without a known one. message_: the gift's note is over 240 characters or its signature over 40. gift_: the gift's note or signature holds a link: a URL scheme (https://, any scheme://), mailto:, www., or a domain with a listed TLD (example.com, bit.ly, t.me/x). The exact rule is the server's model. (GIFTOFPRIVACY.md §10.2), which the site mirrors. gift_: with this order's recipients, the buyer's email (case-insensitive) would pass 20 friend emails in 24 hours: the recipients of its delivery them orders of the last 24 hours that are pending or paid. Delivery me has no daily limit beyond max_quantity cards per order. A pending order whose Gamma purchase was voided is not counted. payment_: an earlier gift's Gamma payment is still being processed (sent to the chain, or landed and being credited), so a new gift purchase with Gamma (/pay/gift/gamma-intent), or the cancel of that purchase (/pay/gift/gamma-cancel), must wait; try again in a few minutes. incorrect_: a Stripe trial's card failed its CVC check when it was attached, so the trial did not start, no Pro was credited, and the card is never charged. Only the purchase report (/subscription/verify-stripe-checkout) answers it, with status invalid. The buyer checks the card details and tries again with a new payment sheet or checkout session. Absent from older servers; clients fall back to message for an absent or unknown code.
One step of the validator's routing-verification protocol. The route accepts two body shapes:
The request must egress from the provider being claimed - the server resolves the hop from the request source IP, never from the body. Authentication is the protocol's own Ed25519 signatures (over the canonical binary messages, not the JSON), not a JWT. A non-final step returns the assign result (the server's signed commitment to the next hop); the final step returns status "complete" and the published proof.
uuid. The validator's own client_id; the server checks vpk equals this client's registered Ed25519 key.
base64 encoded 32-byte Ed25519 validator path key.
base64 encoded 32-byte nonce.
base64 encoded 64-byte Ed25519 SEED signature.
Requested trail depth. The server clamps to its allowed range.
uuid. The validator's own client_id.
uuid
The ordered confirmed hop client_ids plus the single pending hop being claimed.
uuid
base64 encoded 64-byte Ed25519 EXTEND signature.
uuid
base64 encoded 32-byte per-trail server nonce.
The ordered confirmed hop client_ids (ids only; times are published only in the final proof).
uuid
uuid. The newly assigned pending hop.
The server-clamped effective trail depth.
1-byte id of the server key that signed assign_sig. See /verify/keys.
base64 encoded 64-byte Ed25519 ASSIGN signature by the server (msg_type 0x03).
"complete"
uuid
base64 encoded 32-byte per-trail server nonce.
base64 encoded 32-byte Ed25519 validator path key.
Trail depth.
uuid. The canonical provider at this hop.
Server-stamped confirmation time, unix milliseconds UTC.
The 32-byte hash of the provider's egress IP at the subnet's configured prefix granularity. Marshals on the wire as a JSON array of 32 integers (a Go [32]byte), not a base64 string.
1-byte id of the server key that signed final_sig.
The server-attested coverage of the trail (v1 = M-1, the server-assigned confirmed hops with the seed excluded).
base64 encoded 64-byte Ed25519 FINAL signature by the server.
base64 encoded 64-byte Ed25519 depth-M EXTEND signature by the validator.
The published server Ed25519 verify keys, by server_key_id. All historical keys are listed so old proofs remain verifiable across key rotations.
1-byte key rotation id.
base64 encoded 32-byte Ed25519 public key.
The public reproducibility index of the routing-verification protocol: per provider and period, how many hops were assigned and how many were confirmed, the resulting reliability in parts per million, and the latency percentiles when they were measured. The answer names the profile and policy hash the rows were produced under, plus the egress hash key id (the id only -- the key itself never leaves the server), so a third party can check that two indexes are comparable.
Unauthenticated, and it does not participate in validator scoring. 503 while the subnet subsystem is disabled.
RFC 3339 start of the window.
RFC 3339 end of the window.
The id only; the key itself never leaves the server.
The published completed trails, so anyone can re-verify them against the keys from /verify/keys. Same window parameters, profile and policy hash as /verify/. Unauthenticated; 503 while the subnet subsystem is disabled.
RFC 3339 start of the window.
RFC 3339 end of the window.
Recover the first signed answer to a verification request after a lost reply. The body locates the original request: its client_id, the exact request message (base64, at most 2048 bytes), its signature (base64, 64 bytes) and, when the original was scoped, its scope. No JWT: the request signature must verify. At most 16 KiB.
The answer's original carries the retained signed transition (its exact body and signature, both base64) or null when none is retained. It is not a signed assertion that an absent request did not run; readers verify the returned signature, scope and bytes themselves.
The original's deployment scope, as the original was signed; omit for an unscoped original.
The exact original request message, base64; at most 2048 bytes.
The request signature, base64; 64 bytes.
The retained signed transition, or null when none is retained.
The exact signed body, base64.
The transition signature, base64.
Close one verification request for good, or recover its signed answer when it already ran. The body is the request owner's signed closure: the original request message and request_, its client_id, the epoch request cut that holds the request (cut_hash, epoch and end_block), the deployment scope, and the owner's closure signature. No JWT: the request signature and the closure signature must both verify under the key in the request message, and scope must be this deployment's. The caller's source address and the request key count against the POST /verify seed rate limits.
When the request already ran, the answer is its retained signed original (original). Otherwise the server retains the closure and its signed closed_ receipt in one commit, and the request can no longer run. Exactly one of the two is present. An exact retry returns the first receipt, signed by the server key of that time; a different closure for a closed request is refused.
The framing is strict: exactly one Content-Type: application/ (no parameters), a positive Content-Length of at most 8192 bytes, no query, and no content encoding, transfer encoding or trailers. The body must be exactly the canonical encoding of the closure; any re-encoding is refused.
The body is streamed: the server reads it at the client's pace, and it must be complete within 60 seconds; the whole operation, upload included, has 300 seconds. The server runs at most four closures at once per API instance. A refusal decided before the body is read (not enabled, busy, too large, misframed) is answered at once, and the server then reads and discards at most 1 MiB more of the body, for up to 5 seconds, before it stops reading, so a client should stop sending when a response arrives. Refusals are plain text, not JSON.
urnetwork-provider-attempt-request-close-v1 followed by one NUL character, \u0000 in the JSON.
The deployment scope the request was signed under; it must be this deployment's.
The 32-byte chain genesis hash, a JSON array of 32 integers.
The 32-byte policy hash, a JSON array of 32 integers.
The request's client id.
The exact original SEED or EXTEND request message, base64.
The request's 64-byte Ed25519 signature, base64.
The 32-byte hash of the epoch request cut that holds the request, a JSON array of 32 integers.
The epoch of that cut.
The end block of that cut.
The owner's 64-byte Ed25519 closure signature, base64.
The request already ran. Its retained signed transition, as POST /verify/ returns it.
The exact signed body, base64.
The transition signature, base64.
The request is closed: the server's signed receipt that it holds no original for the request and will not run it. It asserts this execution fence only, not coverage, eligibility or traffic. body is the canonical JSON of schema (urnetwork-provider-attempt-closed-unreceived-v1 followed by one NUL character), closure_hash (the SHA-256 of the exact closure, a JSON array of 32 integers) and server_, the /verify/keys key whose Ed25519 signature covers that schema string followed by body.
The exact receipt body, base64.
The server key's Ed25519 signature, base64.
Read the retained owner statements of one SDK client and key, for the subnet provider work protocol. Public and self-authenticating: the returned originals carry their own signatures.
The query takes exactly domain (64 hex), client (32 hex) and key (64 hex), plus an optional generation (32 hex); selectors are lowercase hex, not all zeros, each given once, with no other parameters, and domain must be this deployment's.
generation: the exact original owner statement, with an ETag of its SHA-256 and Cache-Control: public, immutable.32 hex digits. Selects one exact owner statement.
Each retained original owner statement, base64.
List the outstanding original work requests for one SDK client, generation and key. The query takes exactly domain (64 hex), client (32 hex), generation (32 hex) and key (64 hex), with the same selector rules as /provider-work/.
32 hex digits.
Each original request, base64.
Read one original work request by the SHA-256 of its exact bytes. The answer is the original JSON, with an ETag of the hash and Cache-Control: public, immutable. No query parameters.
64 lowercase hex digits.
Read one original work cut by the SHA-256 of its exact bytes. The answer is the original JSON, with an ETag of the hash and Cache-Control: public, immutable. No query parameters.
64 lowercase hex digits.
Read the closed-work whole inventory published for one subnet payout artifact. The query takes exactly domain (64 hex), epoch (a canonical decimal uint64) and artifact (64 hex), plus an optional authority (64 hex) that selects an exact authority. A historical absence is answered as missing; it is never rebuilt from current state.
A canonical decimal uint64.
64 hex digits, the artifact's content hash.
64 hex digits. Selects an exact authority.
The coldkeys attached inside the caller's network: the network consent, the hotkey entry and the network-level wallet (no client_id) and every provider client's wallet. consent_ is provider or network for an entry that is a wallet mapping consent, hotkey for the network's accepted hotkey delegation, and absent for a wallet set by a login proof and for the network-level copy; release settlement pays only the entries with a scope. The network consent is listed before the hotkey entry, and both before the network-level copy, so a client that takes the first network-level entry follows settlement's order. wallet is the session's effective wallet in settlement's precedence: for a client session its own provider consent, else the network consent, else the hotkey entry, else its own wallet without a consent, else the network-level copy; for a network session the network consent, else the hotkey entry, else the network-level copy. Absent when none is attached. An empty wallets list is not an error.
The coldkey as an ss58 address. For the hotkey entry, the coldkey of the hotkey wallet consent generation effective at the current epoch, or of the head generation when none is effective yet.
uuid of the provider client; absent for the network-level wallet.
Unix time in milliseconds the wallet was set.
provider for a provider client's wallet mapping consent, network for the network consent (no client_id), hotkey for the network's accepted hotkey delegation (no client_id). Absent for a wallet that is not a consent.
For a consent, the first epoch it pays. For the hotkey entry, the delegation's.
For a consent, the last epoch it pays. For the hotkey entry, the delegation's.
For the hotkey entry, the delegated hotkey as an ss58 address. Absent for the other scopes.
For the hotkey entry, the hotkey wallet consent head the delegation adopts, as 0x and 64 hex digits. Absent for the other scopes.
For the hotkey entry, the generation of that consent head. Absent for the other scopes.
For the hotkey entry, the delegation chain head (sha256 of the retained delegation), as 0x and 64 hex digits. Absent for the other scopes.
For the hotkey entry, the generation of the delegation chain head. Absent for the other scopes.
The coldkey as an ss58 address. For the hotkey entry, the coldkey of the hotkey wallet consent generation effective at the current epoch, or of the head generation when none is effective yet.
uuid of the provider client; absent for the network-level wallet.
Unix time in milliseconds the wallet was set.
provider for a provider client's wallet mapping consent, network for the network consent (no client_id), hotkey for the network's accepted hotkey delegation (no client_id). Absent for a wallet that is not a consent.
For a consent, the first epoch it pays. For the hotkey entry, the delegation's.
For a consent, the last epoch it pays. For the hotkey entry, the delegation's.
For the hotkey entry, the delegated hotkey as an ss58 address. Absent for the other scopes.
For the hotkey entry, the hotkey wallet consent head the delegation adopts, as 0x and 64 hex digits. Absent for the other scopes.
For the hotkey entry, the generation of that consent head. Absent for the other scopes.
For the hotkey entry, the delegation chain head (sha256 of the retained delegation), as 0x and 64 hex digits. Absent for the other scopes.
For the hotkey entry, the generation of the delegation chain head. Absent for the other scopes.
Attach the caller's subnet coldkey - the ss58 address that pool payouts are claimable by. Proof of key possession is required: message is the single-use challenge issued by POST /auth/wallet-challenge for blockchain TAO and signature is the coldkey's sr25519 signature over it. client_id scopes the wallet to one provider client (a client-scoped JWT selects its own client). Banned addresses are rejected. Not retroactive: the wallet applies from the next committed epoch's leaf set. This wallet is deliberately separate from the account payout wallet.
A well-formed signature that does not verify for coldkey_ss58 over message is refused with error.code signature_.
A message issued by POST /sn/wallet/consent (it starts with "Approve URnetwork provider wallet mapping") is a per-provider wallet mapping consent, one issued by POST /sn/wallet/network-consent (it starts with "Approve URnetwork network wallet mapping") is a network consent, and one issued by POST /sn/wallet/hotkey-delegation (it starts with "Delegate URnetwork network wallet to hotkey") is a hotkey delegation. A consent or delegation is retained as signed and the result carries its mapping_hash and mapping_; submitting the same one again returns the same values. A network consent and a hotkey delegation are accepted only from the network owner's session (a network JWT) and without client_id. A hotkey delegation is signed by the hotkey it names, not by a coldkey: signature is the hotkey's sr25519 signature and coldkey_ss58 is the hotkey's ss58 address.
The subnet coldkey as an ss58 address (Bittensor prefix 42).
uuid of the provider client the wallet is attached to. Defaults to the session client for a client-scoped JWT; must belong to the caller's network.
The coldkey's sr25519 signature (hex) over message. Required for app callers.
The exact single-use challenge text issued by POST /auth/wallet-challenge for blockchain TAO and this address.
A stable code for a refusal that has one, so a client can pick a localized message. signature_: the signature is well formed but does not verify for coldkey_ss58 over message. In practice the wallet signed with another account than the address entered, or signed other text. An sr25519 signature cannot be recovered to the key that made it, so the server cannot name that account. Sign the issued challenge with the entered address. Malformed input and a wrong, used or expired challenge carry no code. Absent from older servers and for other refusals; clients fall back to message for an absent or unknown code.
For an accepted wallet mapping consent, the hex sha256 of the retained signed consent; the chain head at mapping_.
For an accepted wallet mapping consent, its generation in its chain (1 for the first consent).
Issue a per-provider wallet mapping consent: the exact message the coldkey signs to receive one provider client's earnings for the inclusive epochs from_epoch to through_. A client-scoped JWT names its own client; a network JWT may name a client of its network with client_id. The message is valid for 5 minutes and is submitted unchanged, with the coldkey's sr25519 signature, to POST /sn/wallet. A provider's own consent effective at an epoch takes precedence over the network consent.
uuid of the provider client. Defaults to the session client for a client-scoped JWT; must belong to the caller's network.
The coldkey as an ss58 address (Bittensor prefix 42).
The first epoch the consent pays. It must be after the operator's current finalized epoch.
The last epoch the consent pays, at most 65535 epochs after from_epoch.
The exact text the coldkey signs (sr25519, substrate context, raw or in the <Bytes> wrapper). Submit it unchanged.
The retained signed consents of one provider client, generation 1 through generation, for a caller that already holds the chain head (head_hash, generation) from an independent source. A head that does not match is refused; the server never selects the newest consent as authority. No authentication: the consents are public evidence.
The deployment domain the consents were issued in, as it appears in each signed consent.
uuid of the provider client.
The 32 bytes of the chain head (sha256 of the retained consent), as an array of integers.
The head's generation.
The signed consents, or hotkey delegations, in generation order.
The 64-byte sr25519 signature as an array of integers.
Issue a network wallet mapping consent: the exact message the coldkey signs once to receive the earnings of every provider client of the caller's network, current and future, for the inclusive epochs from_epoch to through_. Only the network owner's session (a network JWT) may request it; a client-scoped JWT is refused. A client with its own provider consent effective at an epoch earns to that consent instead. The message is valid for 5 minutes and is submitted unchanged, with the coldkey's sr25519 signature and without client_id, to POST /sn/wallet. A later consent replaces the earlier one from its from_epoch; there is no unsigned revocation.
The coldkey as an ss58 address (Bittensor prefix 42).
The first epoch the consent pays. It must be after the operator's current finalized epoch.
The last epoch the consent pays, at most 65535 epochs after from_epoch.
The exact text the coldkey signs (sr25519, substrate context, raw or in the <Bytes> wrapper). Submit it unchanged.
The retained signed network consents of one network, generation 1 through generation, for a caller that already holds the chain head from an independent source. As for /sn/wallet/consent/history, a head that does not match is refused and no authentication is required.
The deployment domain the consents were issued in, as it appears in each signed consent.
uuid of the network.
The 32 bytes of the chain head (sha256 of the retained consent), as an array of integers.
The head's generation.
The signed consents, or hotkey delegations, in generation order.
The 64-byte sr25519 signature as an array of integers.
Store a hotkey wallet consent chain: a coldkey's approval, signed once for every operator of the subnet, that the networks which delegate to a hotkey earn to that coldkey. originals is the complete chain from generation 1, each consent signed by both the coldkey and the hotkey. The chain is verified and must name this operator's subnet. It is stored idempotently, so submitting it again returns the same head; a chain whose consent at a stored generation differs (a fork) is refused. A later generation replaces the earlier one from its from_epoch and may name another coldkey. Storing a chain attaches no wallet: a network earns through it only from a hotkey delegation (POST /sn/wallet/hotkey-delegation) that adopts its head. Requires a network JWT of the network's administrator; a client JWT is refused.
Nothing issues these chains, so storage is bounded per submitting network: a network may link at most 8 distinct hotkeys (a ninth is refused with 403), and one request may add at most 64 generations the operator doesn't have yet (more is refused with 400; submit successive prefixes of the chain instead). Resubmitting or extending a hotkey the network already linked is always allowed.
The complete chain of signed consents in generation order, from generation 1.
The exact consent text both keys signed. It starts with "Approve URnetwork hotkey wallet mapping".
The coldkey's 64-byte sr25519 signature over message (substrate context, raw or in the <Bytes> wrapper), as an array of integers.
The hotkey's 64-byte sr25519 signature over message, made the same way, as an array of integers.
The hotkey the chain names, as an ss58 address (Bittensor prefix 42).
The 32 bytes of the chain head (sha256 of the head consent), as an array of integers.
The head's generation.
The stored hotkey wallet consents of one hotkey on this operator's subnet, generation 1 through generation, for a caller that already holds the chain head from an independent source. As for /sn/wallet/consent/history, a head that does not match is refused and no authentication is required.
The hotkey as an ss58 address (Bittensor prefix 42).
The 32 bytes of the chain head (sha256 of the retained consent), as an array of integers.
The head's generation.
The signed consents in generation order.
The exact consent text both keys signed. It starts with "Approve URnetwork hotkey wallet mapping".
The coldkey's 64-byte sr25519 signature over message (substrate context, raw or in the <Bytes> wrapper), as an array of integers.
The hotkey's 64-byte sr25519 signature over message, made the same way, as an array of integers.
Issue a hotkey delegation: the exact message the hotkey signs to receive the earnings of every provider client of the caller's network, current and future, for the inclusive epochs from_epoch to through_. Each epoch earns to the coldkey that the hotkey's stored wallet consent chain, through the head consent_, makes effective at it. That chain must be stored first (POST /sn/wallet/hotkey-consent) and name hotkey_ss58. Only the network owner's session (a network JWT) may request it; a client-scoped JWT is refused. A client with its own provider consent, or a network with a network consent, effective at an epoch earns to that consent instead. The message is valid for 5 minutes and is submitted unchanged, with the hotkey's sr25519 signature and without client_id, to POST /sn/wallet. A later delegation replaces the earlier one from its from_epoch and may name another hotkey.
The hotkey as an ss58 address (Bittensor prefix 42); the stored consent chain must name it.
The 32 bytes of the hotkey wallet consent head the delegation adopts (sha256 of that consent), as an array of integers.
The consent head's generation.
The first epoch the delegation pays. It must be after the operator's current finalized epoch.
The last epoch the delegation pays, at most 65535 epochs after from_epoch.
The exact text the coldkey signs (sr25519, substrate context, raw or in the <Bytes> wrapper). Submit it unchanged.
The retained signed hotkey delegations of one network, generation 1 through generation, for a caller that already holds the chain head from an independent source. Each original's signature is the hotkey's. As for /sn/wallet/consent/history, a head that does not match is refused and no authentication is required.
The deployment domain the delegations were issued in, as it appears in each signed delegation.
uuid of the network.
The 32 bytes of the chain head (sha256 of the retained delegation), as an array of integers.
The head's generation.
The signed consents, or hotkey delegations, in generation order.
The 64-byte sr25519 signature as an array of integers.
Checks an address before it is attached: ss58 syntax with the Bittensor prefix, the operator ban list, and whether the account exists on the subtensor chain. When the chain cannot be reached the result reports exists_ with a message, so an outage never blocks a user. No authentication; chain lookups are rate limited per source address.
The ss58 address to check.
The address decodes as ss58 with the Bittensor prefix.
The account exists on the subtensor chain (true when the chain could not be reached; see message).
The address is on the operator ban list and must not be attached.
The caller network's standing for a head mining spot (Top 200, WHITEPAPER 8.4), read from the Protocol leaderboard's newest snapshot (GET /sn/top), so this route, the Top 200 page and the Protocol tab agree: score is the network's projected_, floor the snapshot's projected_ (the projected 200th score), and rank_ the network's 1-based position (0 when it is not ranked). Before the board's first snapshot they come from the live estimate instead: split-adjusted distinct routable egress-IP breadth from the live trail egress index, with floor the score of the last network inside cutoff (0 while fewer networks score). bound/hotkey/uid reflect an active head binding. source is "server" until validators publish consensus scores on chain; a chain outage degrades to the estimate, never an error.
The estimate places the network inside the cutoff.
The network's projected_ in the Protocol leaderboard's newest snapshot; before the first snapshot, the live estimate of split-adjusted distinct routable egress-IP breadth.
The snapshot's projected_, the projected 200th score; before the first snapshot, the score of the last network inside the cutoff (0 while fewer networks score).
The network's 1-based position on the board; 0 when it is not ranked.
Head-tier size (200).
An active head binding exists for one of the network's clients.
The bound head hotkey as ss58; absent when not bound.
The bound uid; 0 when not bound.
The bound network's estimated rank; 0 when not bound.
The current contract epoch.
"server" (estimate) or "chain" (validator consensus).
Store a device's consent for a fleet binding (WHITEPAPER 11.4): the canonical binding payload and the client's Ed25519 signature over its keccak256 digest, optionally with the head hotkey's sr25519 signature. When both signatures verify the response carries the bindFleetMember calldata for the operator to submit from their own key. The server never submits on chain.
0x-hex coordinator contract address.
uuid
0x-hex 32-byte client Ed25519 public key.
The device's Ed25519 signature (hex) over the binding digest; signature is accepted as an alias.
The head hotkey's sr25519 signature (hex) over the same digest; optional, required for calldata.
Optional override of the binding's hotkey (ss58 or 0x-hex).
0x-hex keccak256 binding digest.
Both signatures verified and calldata is present.
0x-hex bindFleetMember calldata for the operator to submit.
The coordinator contract address to send the calldata to.
Same as calldata.
The Protocol leaderboard (server LEADERTOP.md): networks ranked the way the SN25 validator picks its Top 200 head fleets, so a network that has not claimed a UID can see whether it would make the head if it claimed now. Each network is scored as one hypothetical fleet of its verify-eligible providers with the validator's head formula: the distinct /29 (IPv4) or /48 (IPv6) egress prefixes they provide from, each shared prefix split among every network and claimed fleet on it, smoothed with the validator's EMA of a quarter per tempo. Claimed networks also list their fleets, with the validator's own ranking and the on-chain incentive where those are known.
The board is a snapshot computed once per tempo (360 blocks, about 72 minutes); stale is set when the newest one is more than 3 tempos old. projected_, the projected score of the 200th unit (network or claimed fleet), is the line every margin and label is measured against.
rows cover the top 400 positions only, so networks just outside the 200 line can follow their progress. Pages use a keyset cursor pinned to the snapshot of the page that returned it: pass next as cursor until it is null. snapshot pins the first page to one snapshot, and filter lists unclaimed or claimed networks only. Before the board's first snapshot the answer has no rows, and its snapshot has an empty id.
No authentication is required. With a bearer token the response also carries me, the caller's own row wherever it ranks, and the caller's row in rows has is_me set. Rows are anonymous by default: no row carries a network id, and a row in rows has a name only when its network turned on the "show my network name" switch (/network/points-ranking-visibility), the one switch for this board and the points leaderboard. An anonymous claimed row is known only by its fleets' UIDs. Prefix hashes and addresses are never returned, only counts.
Page size, default 50, at most 200; a larger one is served as 200.
Continues from a previous page's next. Opaque, and pinned to the snapshot of the page that returned it. Omit for the first page.
Which networks to list: every ranked network, the ones that have not claimed a UID, or the ones that have.
A snapshot id to read the first page from. Absent means the newest snapshot.
Opaque; the snapshot query parameter of GET /sn/top reads from it. Empty before the board's first snapshot.
The SN25 tempo the snapshot folds in.
The chain block the snapshot was computed at.
The settlement epoch whose pinned prefix hashes the snapshot uses.
Networks ranked in the snapshot.
Head seats on SN25 (200).
Fleets bound on SN25.
Head seats that claimed fleets leave open.
The projected score of the 200th unit (network or claimed fleet): the line every margin and label is measured against.
The current floor among claimed fleets; null when no fleet has claimed.
Fleet binding is open on mainnet. While it is closed no fleet can claim a head seat, and the apps say that claiming isn't open yet.
The state of fleet binding in English, such as "Top 200 binding isn't open on mainnet yet".
Providers in the validator's verify cohort, the ones it can measure.
How many providers the verify cohort holds.
When the validator's latest signed head summary arrived; null without one.
When on-chain incentive was last read; null before the first read.
The measured precision of the projected top 200 against the validator's selection, from 0 to 1; null until fleets bind. The likely label switches on at 0.9.
The snapshot was computed more than 3 tempos ago.
The page's rows in position order, within the top 400 positions.
The 1-based position in the snapshot's total order; 0 in GET /sn/top/me when the network is not ranked.
The network name, set in rows only when the network turned on its "show my network name" switch (/network/points-ranking-visibility); "" when the row is anonymous.
The network's emoji tag; "" when unset.
The projected head score, smoothed with the validator's EMA.
The projected raw score of the last tempo, before smoothing.
The projected_ relative to the snapshot's projected_, as a fraction of the cutoff: positive above the Top 200 line, negative below it.
Positions moved since the previous tempo's snapshot; positive is up.
Distinct /29 (IPv4) or /48 (IPv6) egress prefixes the network's providers provide from.
How many of those prefixes another network or claimed fleet also provides from.
How present the network's providers were over the last tempo, from 0 to 1.
The recommendation. not_ when the validator cannot measure the network (measurable is false). Otherwise estimate until the snapshot's precision_ reaches 0.9, and after that likely (a margin of +0.20 or more, and measurable in at least 3 of the last 4 tempos), borderline (a margin within 0.20 of the line either way) or unlikely (a margin of -0.20 or less).
The validator can measure the network; its providers are in the verify cohort.
The network has verify-eligible providers.
The apps prompt the network to claim a head seat: it is measurable, its position is 200 or better, and it has no active claimed fleet. A network that already claimed is not prompted. Apps use this flag rather than computing it.
The row is the caller's own network; false without a bearer token.
The network's claimed fleets; empty when it has not claimed.
The fleet's UID on SN25.
The binding generation.
The settlement epoch the binding is valid until.
The fleet's exact replica score; null until authenticated evidence and prior state are available for replay.
The validator's own head score for the fleet, from its signed head summary; null without one.
The fleet's 1-based rank among the fleets the validator ranked; null without a head summary.
How many fleets the validator ranked; null without a head summary.
The validator selected the fleet into the Top 200; null without a head summary.
The UID's share of SN25 incentive, a fraction from 0 to 1 (the chain's Incentive, a share of 65535); null before it is first read. 0.018 is 1.8%.
incentive is stale: the validator's weights on chain are its fallback row, or they are outside the activity cutoff.
The caller's own row wherever it ranks; null when the request is not signed in or the caller's network is not ranked.
The 1-based position in the snapshot's total order; 0 in GET /sn/top/me when the network is not ranked.
The network name, set in rows only when the network turned on its "show my network name" switch (/network/points-ranking-visibility); "" when the row is anonymous.
The network's emoji tag; "" when unset.
The projected head score, smoothed with the validator's EMA.
The projected raw score of the last tempo, before smoothing.
The projected_ relative to the snapshot's projected_, as a fraction of the cutoff: positive above the Top 200 line, negative below it.
Positions moved since the previous tempo's snapshot; positive is up.
Distinct /29 (IPv4) or /48 (IPv6) egress prefixes the network's providers provide from.
How many of those prefixes another network or claimed fleet also provides from.
How present the network's providers were over the last tempo, from 0 to 1.
The recommendation. not_ when the validator cannot measure the network (measurable is false). Otherwise estimate until the snapshot's precision_ reaches 0.9, and after that likely (a margin of +0.20 or more, and measurable in at least 3 of the last 4 tempos), borderline (a margin within 0.20 of the line either way) or unlikely (a margin of -0.20 or less).
The validator can measure the network; its providers are in the verify cohort.
The network has verify-eligible providers.
The apps prompt the network to claim a head seat: it is measurable, its position is 200 or better, and it has no active claimed fleet. A network that already claimed is not prompted. Apps use this flag rather than computing it.
The row is the caller's own network; false without a bearer token.
The network's claimed fleets; empty when it has not claimed.
The fleet's UID on SN25.
The binding generation.
The settlement epoch the binding is valid until.
The fleet's exact replica score; null until authenticated evidence and prior state are available for replay.
The validator's own head score for the fleet, from its signed head summary; null without one.
The fleet's 1-based rank among the fleets the validator ranked; null without a head summary.
How many fleets the validator ranked; null without a head summary.
The validator selected the fleet into the Top 200; null without a head summary.
The UID's share of SN25 incentive, a fraction from 0 to 1 (the chain's Incentive, a share of 65535); null before it is first read. 0.018 is 1.8%.
incentive is stale: the validator's weights on chain are its fallback row, or they are outside the activity cutoff.
The cursor of the next page; null on the last page.
The caller network's standing on the Protocol leaderboard (GET /sn/top), from the same snapshot: its row; the score it would have if it claimed alone today, with no other network or fleet on its prefixes claiming; its distinct and shared prefix counts and how many other networks and claimed fleets share them; why the validator cannot measure it, when it cannot; and its rank and score for each day of up to the last 90, for a progress chart. Counts only, never prefix hashes or addresses. A network that is not ranked has a row with position 0 and the label not_.
Opaque; the snapshot query parameter of GET /sn/top reads from it. Empty before the board's first snapshot.
The SN25 tempo the snapshot folds in.
The chain block the snapshot was computed at.
The settlement epoch whose pinned prefix hashes the snapshot uses.
Networks ranked in the snapshot.
Head seats on SN25 (200).
Fleets bound on SN25.
Head seats that claimed fleets leave open.
The projected score of the 200th unit (network or claimed fleet): the line every margin and label is measured against.
The current floor among claimed fleets; null when no fleet has claimed.
Fleet binding is open on mainnet. While it is closed no fleet can claim a head seat, and the apps say that claiming isn't open yet.
The state of fleet binding in English, such as "Top 200 binding isn't open on mainnet yet".
Providers in the validator's verify cohort, the ones it can measure.
How many providers the verify cohort holds.
When the validator's latest signed head summary arrived; null without one.
When on-chain incentive was last read; null before the first read.
The measured precision of the projected top 200 against the validator's selection, from 0 to 1; null until fleets bind. The likely label switches on at 0.9.
The snapshot was computed more than 3 tempos ago.
The 1-based position in the snapshot's total order; 0 in GET /sn/top/me when the network is not ranked.
The network name, set in rows only when the network turned on its "show my network name" switch (/network/points-ranking-visibility); "" when the row is anonymous.
The network's emoji tag; "" when unset.
The projected head score, smoothed with the validator's EMA.
The projected raw score of the last tempo, before smoothing.
The projected_ relative to the snapshot's projected_, as a fraction of the cutoff: positive above the Top 200 line, negative below it.
Positions moved since the previous tempo's snapshot; positive is up.
Distinct /29 (IPv4) or /48 (IPv6) egress prefixes the network's providers provide from.
How many of those prefixes another network or claimed fleet also provides from.
How present the network's providers were over the last tempo, from 0 to 1.
The recommendation. not_ when the validator cannot measure the network (measurable is false). Otherwise estimate until the snapshot's precision_ reaches 0.9, and after that likely (a margin of +0.20 or more, and measurable in at least 3 of the last 4 tempos), borderline (a margin within 0.20 of the line either way) or unlikely (a margin of -0.20 or less).
The validator can measure the network; its providers are in the verify cohort.
The network has verify-eligible providers.
The apps prompt the network to claim a head seat: it is measurable, its position is 200 or better, and it has no active claimed fleet. A network that already claimed is not prompted. Apps use this flag rather than computing it.
The row is the caller's own network; false without a bearer token.
The network's claimed fleets; empty when it has not claimed.
The score the network would have if it claimed alone today, with no other network or fleet on its prefixes claiming.
Distinct /29 (IPv4) or /48 (IPv6) egress prefixes the network's providers provide from.
How many of those prefixes another network or claimed fleet also provides from.
How many other networks and claimed fleets share the network's prefixes.
Why the validator cannot measure the network; "" when it can. not_: its providers aren't in the verify cohort. shared_: its providers share an egress address with another network. not_: none of its devices provides.
The network's projected rank and score for each day, at most 90 days.
The day, YYYY-MM-DD.
The caller network's merkle pool-payout claim for an epoch: everything needed to call claim on the subnet contract. Claims are served once the epoch is finalized on chain.
Epoch index. Absent means the latest finalized epoch -- and only absence defaults, since epoch 0 is a real epoch.
Epoch index.
base64 encoded 32-byte network operator id, as committed on chain.
base64 encoded 32-byte coldkey public key (the ss58-decoded key set via /sn/wallet).
The caller's payout share in basis points.
Merkle proof from the (no_id, coldkey, share_bps) leaf to payout_root.
base64 encoded 32-byte committed payout merkle root.
0x-hex EVM address of the subnet contract.
EVM chain id of the subnet contract chain.
Block number claims open at.
The content hash of the payout artifact this claim was computed from, when one is recorded. Fetch it from /sn/artifact.
Where that artifact is published, when recorded.
0x-hex EVM address of the settlement vault the claim is sent to; absent when the operator has not configured one.
The current subnet epoch index, boundaries, and deadlines mirrored from chain, so clients do not need their own RPC.
Epoch index.
Epoch length in blocks.
EVM chain id of the subnet contract chain.
Genesis block hash of the subnet chain, 0x and 64 lowercase hex digits, which with chain_id and netuid names the subnet; absent when unset.
0x-hex EVM address of the subnet contract.
0x-hex EVM address of the settlement vault claims are sent to; absent when unset.
The operator id (decimal string); absent when unset.
Public subtensor EVM JSON-RPC url for clients; absent when unset.
Serve a canonical payout artifact addressed by its sha256 content hash. The hash is rechecked against the bytes before anything is returned, so a corrupt object store cannot silently substitute a different payout tree. Public and immutable: the answer carries the content hash as its ETag and a one-year immutable cache directive.
The artifact's sha256 content hash.
Always urnetwork-payout-artifact-v1.
0x-prefixed hex digest.
0x-prefixed 20-byte EVM address.
0x-prefixed 20-byte EVM address.
0x-prefixed hex digest.
0x-prefixed block hash.
0x-prefixed block hash.
sha256:-prefixed hex digest.
sha256:-prefixed hex digest.
sha256:-prefixed hex digest.
The provider inputs the tree was built from; null when the epoch had no providers (a nil slice in the builder).
The 16-byte client id, as a JSON array of byte values.
The 32-byte coldkey public key, as a JSON array of byte values.
Sibling hashes from the leaf to the root, each a 32-byte value as a JSON array of byte values; null for a tree that needs none.
The 32-byte merkle root, as a JSON array of byte values.
RFC 3339 UTC.
0x-prefixed 20-byte EVM address of the signing key.
0x-prefixed hex of the 65-byte secp256k1 signature over content_hash.
List immutable payout artifact keys under a deployment and netuid prefix, optionally narrowed to one epoch and one operator id. Only public object identifiers are returned -- never signer or vault material. The page is validated as an integrity boundary before it is served: keys must be strictly increasing, inside the requested prefix, and named by a canonical lowercase 32-byte hex hash with a .json suffix.
One safe path segment (no /, \ or .).
A nonzero uint16.
A uint64. Required if no_id is given.
A nonzero uint64 operator id; only valid with epoch.
Objects per page, default 256.
The previous page's next_after; must be inside the same prefix.
Always urnetwork-payout-artifact-history-v1.
sha256: followed by the lowercase 64-character hex hash.
The cursor for the next page; empty on the last page.
Serve a settlement v2 ledger object addressed by its sha256: a root's ledger header, or one of the provider or account chunks the header names. A root's ledgerHash on chain is the raw sha256 of its header bytes, and the header names each chunk by the same sha256: reference, so a reader checks every object against the hash it asked for. The server checks it too, and never serves bytes whose sha256 differs from the hash. Served whether or not settlement v2 is configured.
Public and immutable: the answer carries the hash as its ETag and Cache-Control: public, immutable, max-age=.
sha256: followed by the 64 lowercase hex digits of the object's sha256.
The coldkey's settlement v2 account in each pool that holds it, one entry per pool in ascending no_id, with what a claim needs: the latest finalized root's cumulative, its bottom-up proof, and vault2's claimed, read at the finalized block tag. The pools are the operator's own, its pool (no_id n) and, while capture the flag is on at this server, its capture the flag pool (no_id 2^32 + n, 4294967297 for operator 1), when the latest finalized root or the pending root holds the coldkey, and any other pool where this server has recorded an account for the coldkey. While capture the flag is off, no capture the flag pool is read or answered, not even one with a recorded account, so none can fail an answer. Amounts are decimal strings of rao. A capture the flag account is claimed from vault2 like any pool's.
Each entry names its pool's kind and a display label. Entries carry every field they carried before, so a client that predates kind shows a capture the flag account as "Pool 4294967297" and claims it like any pool.
An account only in the pending root has a null root_index and proof, and a cumulative and claimed of "0". A coldkey that no root holds, like every coldkey while settlement v2 is not configured, has "accounts": [].
Whole or partial. With partial=true a pool whose ledger cannot be read (its objects cannot be read or do not rebuild its committed root, its roots or accounts cannot be read from the server's database, vault2's claimed cannot be read or is above the finalized cumulative, or a recorded account is not at its index) is left out of accounts and named in unavailable_, and the other pools are answered. A client shows such a pool as unavailable, never as zero. Even then the answer is a 502 when the server cannot tell which pools to answer, because its record of the coldkey's accounts cannot be read.
Without partial=true, as every client that predates unavailable_ asks, no pool is named unavailable: the list is always []. A capture the flag pool whose ledger cannot be read is left out of accounts, and the other pools are answered exactly as before the capture the flag pool existed: such a client keeps the operator's pool's balance, and its capture the flag balance is missing until that pool can be read again. A fault in any other pool's ledger, the operator's pool's above all, still fails the whole answer with a 502, as before, so such a client never takes a partial list of those pools for a whole one. A client that knows unavailable_ sends partial=true, so that it shows a capture the flag pool it cannot read as unavailable rather than leaving it out.
Errors are RFC 9457 problem details. The answer carries Cache-Control: no-store.
Public: a proof only reveals published data, and a claim always pays the leaf's coldkey. sn/api/operator.yml documents this operation too, beside the operator's capture the flag routes, with the same fields.
The coldkey: an ss58 address with the Bittensor prefix (42) and a valid checksum, or 0x and 64 hex digits in either case.
true to answer the pools that can be read and name the others in unavailable_. Without it a capture the flag pool that cannot be read is left out of accounts, unnamed, and any other pool that cannot be read fails the whole answer with a 502.
The coldkey, 0x and 64 lowercase hex digits.
The coldkey's account in each pool that holds it, one entry per pool in ascending no_id; [], never null, for a coldkey that no root holds and while settlement v2 is not configured.
The pool's settlement vault (vault2), 0x and 40 lowercase hex digits.
The pool's vault2 id, which a claim names; the operator's id for its pool, 2^32 + the operator's id for its capture the flag pool.
pool: an operator's pool, paying providers and, from epoch 8, extenders. ctf: an operator's capture the flag pool. A client that does not know a kind shows the entry as a pool.
An English display name for the pool, for clients without a localized one: "Pool 1" for operator 1's pool, as the apps name it, and "Capture the flag" for its capture the flag pool. Not for parsing.
The account's fixed position in the pool's sum tree.
The latest finalized root's index in vault2's roots for the pool; null when the account is only in the pending root.
The account's cumulative in the latest finalized root, a decimal string of rao; "0" when the account is only in the pending root.
The claim proof against the latest finalized root: the siblings from the leaf up, one per tree level, [] at depth 0 (a root of one account); null when the account is only in the pending root.
What vault2 has already paid the account, read at the finalized block tag, a decimal string of rao, never above cumulative; "0" when the account is only in the pending root, which needs no chain read.
The account's cumulative in the pending root, a decimal string of rao; null when there is no pending root or the account is not in it.
With partial=true, the pools whose ledger could not be read, in ascending no_id: whether the coldkey has an account there is unknown. Always [] without partial=true, which leaves a capture the flag pool that cannot be read out of accounts instead.
The pool's settlement vault (vault2), 0x and 40 lowercase hex digits.
pool: an operator's pool, paying providers and, from epoch 8, extenders. ctf: an operator's capture the flag pool. A client that does not know a kind shows the entry as a pool.
A sentence for people, never for parsing.
A sentence for people, never for parsing.
URnetwork claims settlement v2 balances for every consented coldkey and pays the gas: automatically once a balance is worth 0.0125 TAO, and on a Claim now once it clears the 0.0001 TAO transfer floor, at most once per coldkey per 30 days. Claims spend at most 0.01 TAO a day; past that they wait for the next UTC day, which costs nothing, since v2 credit never expires. A device can always claim for itself with its gas key.
This answers for the caller's network: each account of its coldkeys in the operator's pools, its pool and, while capture the flag is on, its capture the flag pool, one row per coldkey and pool with the pool's kind and label; what a claim would pay now, why it is still pending, and whether Claim now can be tapped. A coldkey the network has replaced stays listed while it has an account, since URnetwork keeps claiming it. When one of a coldkey's accounts is due, URnetwork claims the coldkey's other accounts above the transfer floor in the same batch, so those read as queued.
With partial=true an operator's pool whose ledger cannot be read is named in unavailable_ and the others are answered: show that pool as unavailable, never as zero. Without partial=true, as every app that predates unavailable_ asks, no pool is named: a capture the flag pool whose ledger cannot be read is left out, and the operator's pool's accounts, and state, are answered exactly as before the capture the flag pool existed, while any other pool that cannot be read is an error for all of them.
An account whose latest claim URnetwork sent names that claim's transaction, claim_, and what it paid, claim_. A claim anyone else sends after it, the device's own included, ends that.
state is the relay's: running; cap_reached; in_flight, a claim's outcome is not final yet; no_key, no relayer key is configured, so the relay reads and sends nothing; bad_key; not_; not_running, it has no recent pass; chain_; ledger_, the ledger of one or both of the operator's pools cannot be read: while the other pool can be, its accounts are still claimed, and only the unreadable pool's rows read relay_paused; send_failed; low_balance; gas_; griefing_, a claim's gas jumped. Without partial=true, a pass that claimed the operator's pool while only the capture the flag pool could not be read is running, as it was before that pool existed.
An error means the balances could not be read: they are unavailable, never zero, and state still says what the relay is doing.
true to answer the pools that can be read and name the others in unavailable_. Without it a capture the flag pool that cannot be read is left out, unnamed, and any other pool that cannot be read is an error for all of them.
The relay's state. See GET /sn/claim-relay.
The TAO value, in rao of TAO, at which a balance is claimed automatically.
The TAO value, in rao of TAO, under which a claim reverts on chain.
The automatic threshold in rao of α at the relay's last price, 0 without one.
The transfer floor in rao of α at the relay's last price, 0 without one.
Days between two Claim now of one coldkey.
The pool's vault2 id, which a claim names.
pool: an operator's pool, paying providers and, from epoch 8, extenders. ctf: an operator's capture the flag pool. A client that does not know a kind shows the entry as a pool.
An English display name for the pool, for clients without a localized one. Not for parsing.
The account's fixed position in the pool's ledger.
What a claim would pay now, in rao of α.
Its TAO value at the relay's last price, in rao of TAO; 0 without a price.
What a committed root that is not final yet adds, in rao of α.
Why the balance is pending.
Why Claim now cannot be tapped, when it cannot.
When this coldkey's Claim now limit ends, unix milliseconds; absent when none holds.
The transaction of the account's latest claim when URnetwork's relay sent it, while the relay has it on record, about 30 days. Absent for a claim anyone else sent, or before any claim.
What that claim paid, in rao of α; absent without claim_tx_hash.
With partial=true, the operator's pools whose ledger could not be read, in ascending no_id: their balances are unavailable, never zero. Always [] without partial=true, which leaves a capture the flag pool that cannot be read out of accounts instead.
The pool's settlement vault (vault2), 0x and 40 lowercase hex digits.
pool: an operator's pool, paying providers and, from epoch 8, extenders. ctf: an operator's capture the flag pool. A client that does not know a kind shows the entry as a pool.
Queues the balances of one of the caller's network's coldkeys for the relay's next pass, ahead of the balances over the automatic threshold, under the same daily cap: its account in each of the operator's pools whose balance clears the transfer floor, in one batch where the relay batches. A coldkey can do this once per 30 days, counted from when URnetwork pays a tapped claim it would not have sent by itself, so a tap that sends nothing, or only moves an automatic claim ahead, uses nothing up.
requested false with a reason is the answer for a balance that cannot be claimed for now: the same values as an account's claim_. A coldkey that is not the network's, or has no account, reads as nothing_.
A tap names no partial answer, so every app's tap is answered as an app that predates the capture the flag pool is: a coldkey whose only account is in a capture the flag pool that cannot be read reads nothing_, and a tap of a coldkey that also has an account in the operator's pool is answered for that account and, when taken, stays open until that capture the flag pool can be read, so that its account there is claimed then too. A tap that reads no account while a pool other than a capture the flag pool cannot be read gets an error: the balances could not be read.
One of the caller's network's coldkeys, an ss58 address with the Bittensor prefix (42).
Why not, as an account's claim_now_reason.
When this coldkey's Claim now limit ends, unix milliseconds, for a tap the limit refused.
Stream the exact immutable bytes of one attempt object. kind selects the shape: metadata is a JSON document, records and proofs are newline-delimited JSON. hash is the canonical lowercase, nonzero, 0x-prefixed sha256 of those bytes and is what the answer's ETag carries. Exactly these two query parameters are accepted, and a Range header is refused, so a partial read can never be mistaken for the whole object.
Concurrency is bounded (16 readers, each with one fixed 32 KiB copy buffer) and a request that finds no slot is answered 429 with Retry-After. A stream that fails after any bytes have been written is aborted without a clean end-of-body rather than ending in a truncated object that looks complete.
Canonical 0x-prefixed lowercase sha256 of the object.
0x-prefixed sha256 of the first descriptor page; zero for an empty stream.
0x-prefixed sha256 of the chunk bytes.
0x-prefixed sha256 of the next page; zero on the last page.
Upload the exact bytes of one attempt object. Requires a CLIENT jwt. The identity is the same kind and hash pair the reader uses, and the server recomputes the sha256 of the body and refuses anything that differs, so an upload can only ever publish the object it names.
The framing is strict: exactly one Content-Type matching the kind (application/ for metadata, application/ for records and proofs), a positive Content-Length within the object bound (32 MiB for records and proofs, 2 MiB for metadata), and no Content-Encoding, Content-Range, Range, transfer encoding or trailers -- a transformed or partial upload is forbidden. Size is charged against the account's byte budget BEFORE any storage work, and the active upload slots are bounded.
A validator may instead present a signed reserved-upload intent in X-Urnetwork-Validator-Upload, which admits the upload against the api's own reserved lifecycle. The reserved header never bypasses client authentication.
The answer is 204 with the content hash in ETag.
Canonical 0x-prefixed lowercase sha256 of the body.
A signed validator reserved-upload intent.
Serve a signed release-evidence envelope by its content hash. The envelope's signature is re-verified and its content hash re-checked against the requested one before the bytes are returned. Public and immutable, with the content hash as ETag.
0x-hex.
The evidence payload; its shape depends on kind.
0x-hex EVM address of the signing operator artifact key.
sha256: followed by the lowercase hex hash of the canonical bytes.
List the evidence objects of ONE signed run. Both kind and run_id are mandatory, so a public caller cannot enumerate other campaigns or turn a small verifier query into an unbounded deployment scan.
With hash the answer is that one object, fully re-verified (signature, deployment, netuid, kind, run and content hash) rather than merely listed, and after may not be combined with it. The legacy empty-run namespace is readable only by exact hash.
A nonzero uint16.
Read exactly this object instead of paging.
Objects per page, default 256.
The previous page's next_after. Not valid with hash.
Always urnetwork-release-evidence-history-v1.
The cursor for the next page; empty on the last page.
Publish one signed client-key observation and read back that client's key history. A key observation creates a durable signed public statement, so it is an explicit POST owned by an authenticated CLIENT session rather than a side effect of the public GET /key/ lookup, and the request cannot supply a key to sign.
The framing is strict: Content-Type: application/, a positive Content-Length of at most 16 KiB, no content encoding, transfer encoding or trailers. The body must be exactly the canonical encoding of the request -- unknown fields, trailing JSON and any non-canonical re-encoding are refused -- and the full maximum response size is charged against the account's byte budget before any operator signature or public write, so a failed call still pays its admission.
uuid. The client whose key history is being observed.
base64 of the encoded signed observation request, at most 8 KiB. The request cannot supply a key to sign.
The client's signed key history statements, base64 encoded, oldest first.
base64 of the signed observation this call published.
The plural form of /sn/, with the same authenticated, bounded and charged publication contract: one HTTP body never becomes one logical quota item, so the maximum response size is charged once PER request in the batch before any work is done. The body is capped at 1 MiB and the responses come back in request order, each an encoded client-key history response.
A batch whose chain work cannot be admitted is refused with 413 and an X-Ur-Client-Key-Batch-Admission: work header.
A 16-byte client id, on the wire as a JSON array of 16 integers.
A 32-byte hotkey, on the wire as a JSON array of 32 integers.
A 32-byte hash, on the wire as a JSON array of 32 integers.
A 32-byte hash, on the wire as a JSON array of 32 integers (a Go [32]byte).
A 32-byte nonce, on the wire as a JSON array of 32 integers.
One encoded ClientKeyHistoryResponse per request, in request order.
The client's signed key history statements, base64 encoded, oldest first.
base64 of the signed observation this call published.
Issue the caller's welcome offer: 25% off the first year of Pro (3 months free), valid validity_ (5) from issue, stacked on the 14-day trial, redeemable on every store. Issued ONCE per network: the call is idempotent and returns the existing offer in whatever state it is in (created: false); an expired offer is never re-issued. Call it the moment the offer surface renders (the intro plan step), so the deadline is real.
Refused with error when the onboarding config is absent, or when the caller is in the holdout variant of the in-app offer experiment (experiments["offer.in_): those networks show the regular plan picker and reach the offer by email instead.
Budgeted per caller address (30 per 10 minutes): over budget the response is 429 with a Retry-After header.
Where the offer is being shown. Only these three are accepted here; empty means intro_step, and anything else (including email_link, which only the campaign engine issues) is refused with error. "Unknown surface.".
ISO 3166-1 storefront country, when the app knows it
The offer. The key is ABSENT (not null) when refused.
When the offer was first redeemed; null until then.
The store of the first redemption; null until then.
The store of a purchase. A crypto purchase names its coin's market: solana for USDC and SOL, zcash, monero, bittensor for TAO, bitcoin and ethereum.
true for the call that issued the offer
The key is ABSENT (not null) on success.
Store a batch of product events (at most 200 per call) against the CLOSED event schema (see ClientEvent). The network id comes from the bearer token only; tier, path, experiment and variant are stamped by the server. platform is required and must be one of the known platforms: an event without one is rejected. Unknown event names, unknown prop keys, missing required props and ill-typed values are refused PER EVENT in rejected (the rest of the batch is stored); a rejection is final, the client must not resend that event. No free text is stored except feedback., which is redacted (emails, phone numbers, IP addresses) before storage.
Clients batch every 30 s or on background, drop an event after three failed calls, and never send more than 200 per call (a larger batch is a 400). Budgeted per caller address (120 calls per 10 minutes): over budget the response is 429 with a Retry-After header.
free text, redacted (emails, phone numbers, IP addresses) before storage
events stored (or deduplicated)
schema refusals by batch index; final, do not resend
Record a campaign landing-page click. Every button in the onboarding and re-engagement emails links to a landing page, https://, whose <step> is a landing slug (LandingStep): connect, widgets, offer or feedback from an onboarding email, connect, update, keep, learn or winback from a re-engagement email. The page posts the token here and routes by the link's own slug:
connect, widgets, offer and feedback open that screen of the app, passing the token as t: on Android the app link https:// ur.io/ c?onboarding= <step> through an intent that falls back to the Play listing, on iOS urnetwork:// onboarding/ <step> with a link to the App Store if the app does not open, and on a desktop the web app.winback opens the plan screen as offer does (the web app's subscription page on a desktop), or, when the response carries open_url, that link instead: Apple's own page for an App Store win-back offer, https:// apps. apple.com/ win-back/ <id>, the only link the page will open from a response.update opens the app's store listing (the download page on a desktop), and learn the threat model, https:// ur.io/ docs/ threat-model.keep opens nothing: the click itself is the answer to the "should I keep writing?" email, and the page says so once this call has recorded it.The server records the click, as landing. for an onboarding link and reengage. for a re-engagement link (with reengage.keep for a keep link), and answers with the token's step, always a landing slug, and the in-app destination for it. Servers before the change of 2026-11-01 answered an onboarding token with its email template's name (e4b_offer) instead, so a client routes by the slug in the link and reads step only for a link without one. An app open (/network/) within 48 h of an onboarding click is attributed to it as app.opened.
No authentication: the signed token is the credential, and the response carries nothing about the network beyond where its email's button leads (open_url). An expired token still returns step and destination (with ok: false, error: expired) so the page can route without attributing; an invalid token returns ok: false, error: invalid. Budgeted per caller address (60 per 10 minutes) -> 429 with Retry-After.
The landing slug the token routes to, never an email template's name. Absent for an invalid token.
A campaign landing page's slug, the <step> of https://. The onboarding emails link connect, widgets, offer and feedback; the re-engagement emails link connect, update (the app's store listing), keep (the answer to "should I keep writing?", which opens nothing), learn (the threat model) and winback (the plan screen), and their reason buttons resolve to feedback.
The in-app destination for step. connect, widgets, offer and feedback route to their own; winback to onboarding/; update, keep and learn, which the landing page does not open in the app, to onboarding/.
Where the landing page opens instead of the app, when set: on a winback click by a network whose win-back offer is the App Store's, Apple's direct link to that offer (https://), while the offer is active and the link is configured. Absent otherwise, on an expired or invalid token, and from older servers.
Resolve a feedback link token to the rating or reason the one-tap email button stood for, so the in-app feedback screen opens pre-filled. The buttons link to the landing page https:// (1-5) or https://, which calls this endpoint and then opens the app's feedback screen with the answer as r or why and the token as t (https:// on Android, urnetwork:// on iOS, the web app's support page on a desktop). The token carries the step and may carry the rating or reason; r and why override when present.
why is a reason code. The onboarding feedback email's buttons are the four reasons of the apps' feedback screen: not_needed, not_working, trust and other (its older links carry 1 to 4, which resolve to those four in that order). The re-engagement email that asks why the reader stopped adds stopped, slow and switched (its buttons are stopped, slow, not_needed, switched and other); for its links reason is the closest of the apps' four (stopped and slow → not_working, switched → other) and step is feedback.
The tap is the answer, recorded when the link resolves so it counts even if the reader never sends the in-app form: feedback., with the rating or one of the four reasons, for an onboarding link; reengage., with the reason as tapped, for a re-engagement link, whose answer also decides the network's next re-engagement email (or that there is none). The app then submits the form through /feedback/ and reports feedback. through /client/.
No authentication: the signed token is the credential. Budgeted per caller address (60 per 10 minutes) -> 429 with Retry-After.
The signed feedback token from the email link.
Rating 1-5 from the tapped button.
The reason code of the tapped button: not_needed, not_working, trust or other, and on a re-engagement link also stopped, slow or switched. Older onboarding links carry 1 to 4.
The token's landing slug, feedback for every feedback link. Absent for an invalid or expired token.
A campaign landing page's slug, the <step> of https://. The onboarding emails link connect, widgets, offer and feedback; the re-engagement emails link connect, update (the app's store listing), keep (the answer to "should I keep writing?", which opens nothing), learn (the threat model) and winback (the plan screen), and their reason buttons resolve to feedback.
1-5. The key is ABSENT when the link carried no rating (the server omits the zero value rather than sending 0).
The reason code to pre-select; absent when there is none. For an onboarding link, the link's code (not_needed, not_working, trust or other; an older link's 1 to 4 come back as those codes), and a why outside the four is passed back as sent and not recorded. For a re-engagement link, the closest of the four to the reason tapped (stopped and slow → not_working, not_needed → not_needed, switched and other → other), absent when the link carried none of its five reasons.
The rfc 8414 authorization server metadata. Served with Cache-Control: no-store, and identical to the OpenID Connect discovery document below. The issuer it publishes is the hostname clients must use, which is not necessarily the api host this request reached.
rfc 8707.
The OpenID Connect discovery document. The same document as /.well-known/.
rfc 8707.
The authorization server's public signing keys as a JWK set. All current keys are listed so tokens stay verifiable across a rotation.
The rfc 6749 token endpoint, as a form post. Two grants are supported: authorization_ (with the PKCE code_, and optionally the rfc 8707 resource indicator) and refresh_. Clients are public -- the token endpoint auth method is none -- so client_id is always required and there is no client secret.
Errors are the rfc 6749 section 5.2 envelope. The descriptions are deliberately terse and the detail is logged rather than returned, so an error cannot be used to probe which check failed. The response is never cached by a shared cache.
authorization_code grant.
authorization_code grant; must be registered for this client.
authorization_code grant; the PKCE verifier.
authorization_code grant; the rfc 8707 resource indicator.
refresh_token grant.
refresh_token grant; a space-separated subset of the granted scopes.
Dynamic client registration (rfc 7591). Deprecated by the MCP specification in favor of client id metadata documents, and kept for clients that predate it. The endpoint is openly writable, so it is metered per caller address before the body is parsed or anything is stored; over budget it answers 429 with Retry-After. Registered clients are public, so no secret is issued.
Always none -- registered clients are public and have no secret.
Token revocation (rfc 7009), as a form post. Always answers 200 with an empty body: per the rfc a client must not be able to tell an unknown token from a revoked one.
The OpenID Connect userinfo endpoint. Authenticated by an ACCESS TOKEN this authorization server issued, carrying the openid scope -- not by a URnetwork network JWT. The token's audience is the resource it was minted for rather than this issuer, so the audience is deliberately not constrained here.
What the consent page on the ur.io origin needs to render: who is asking, for what scopes, and whether consent is actually required. The caller is the consent page passing through the signed-in user's URnetwork JWT.
The authorization request is validated here, BEFORE anything is rendered, so a hostile request never reaches a screen that could be used to phish approval; an invalid request is reported to the user rather than redirected, because a redirect uri is only trustworthy once it has matched the client's registered set. prompt= forces the screen even when the scopes are already approved. issuer is returned so the page can echo iss when the user declines, as rfc 9207 requires on error responses too.
Defaults to code.
Defaults to S256.
rfc 8707 resource indicator.
consent forces the screen even when the scopes are already approved.
The requested scopes, filtered to the supported set.
Echoed as iss when the user declines, per rfc 9207.
Mint the authorization code for a request the user approved, and return the redirect the consent page should follow. The caller is the ur.io consent page passing through the signed-in user's URnetwork JWT. Consent is recorded HERE rather than when the screen is shown, so an abandoned screen grants nothing. The redirect carries code, the request's state when it had one, and iss per rfc 9207 so the client can detect a mix-up attack.
Defaults to code.
Defaults to S256.
rfc 8707 resource indicator.
consent forces the screen even when the scopes are already approved.
Where the consent page should send the user agent; carries code, iss and any state.