Docs / Reference

API reference

Everything a client or a provider needs to speak Poncho: the 402 quote, the signed note and the header it travels in, how a note is checked, where the protocol describes itself, and every function of the four contracts with its arguments and the errors it can revert with.

The contract sections below are generated from protocol/abi and the contract source, so they change only when the contracts do. Checked against the release of 23 Sep 2026

Overview

Poncho is HTTP 402 with a signature instead of a transaction. A provider answers a paid route with a quote. The agent signs an EIP-712 note for exactly that quote and asks again with the note in one header. The provider checks the note off chain, serves the call, and redeems its notes on Robinhood Chain later, many in one transaction. The vault moves USDG from the payer's balance to the provider and writes a receipt that anyone can read.

Protocol: poncho/1
Network: Robinhood Chain, chain id 4663 (0x1237)
Settlement: USDG, 6 decimals. Every amount in the protocol is USDG atoms: 1000000 is 1 USDG.
Note header: X-Poncho-Note
RPC: https://rpc.mainnet.chain.robinhood.com
Explorer: robinhoodchain.blockscout.com
Descriptor: /.well-known/poncho.json

Addresses

The four Poncho contracts and the two contracts they rely on. This page and Poncho for agents are the only pages on this site that print them. Check an address on the explorer before you send anything to it.

The payment flow

One paid call, as the parties see it. Only the last two rows touch the chain, and the provider decides when they happen.

Agent ProviderThe request, as the route's own docs describe it. No payment yet.
Provider Agent402 Payment Required with a quote: provider, service, route, amount, nonce and deadline.
AgentChecks the quote against its own ceiling, fills in the payer and itself as the agent, and signs the SpendNote with EIP-712. A signature, not a transaction: no gas and no block to wait for.
Agent ProviderThe same request again, with the note and the signature in the X-Poncho-Note header.
ProviderChecks the note: its fields, its signature, and the payer's balance and the key's cap on chain. Serves the call and banks the note.
Provider Agent200 and the response.
Provider VaultLater, when it chooses: trySettleMany (or settleMany) with the banked notes, up to 128 in one transaction.
VaultTakes each amount from the payer's balance, credits the provider less the fee, and emits Settled, the public receipt of that call.

The 402 quote

A route that wants payment answers 402 with content-type: application/json and this body. Every integer that can pass 2⁵³ travels as a decimal string, because a JSON number cannot hold a uint256.

Fields

error "payment_required": Always "payment_required".
protocol "poncho/1": Always "poncho/1".
chainId 4663: Always 4663.
vault string: The PonchoVault the note is signed against, 0x hex.
header string, optional: Where the signed note goes on the retry. Default X-Poncho-Note.
docs string, optional: Optional link to the provider documentation.
quote.provider string: Who is paid, and the only address that may redeem the note.
quote.serviceId string, optional: PonchoRegistry service id, decimal. "0" when the route is not listed.
quote.routeId string, optional: PonchoRegistry route id, decimal. "0" when the route is not listed.
quote.amount string: USDG atoms, 6 decimals, decimal string.
quote.nonce string: Any value the provider picks, decimal string. The note hash is what is consumed.
quote.deadline integer: Unix seconds after which the note cannot be redeemed.

The quote leaves out payer and agent on purpose: only the agent knows which balance it spends from. The agent copies every other field into the note unchanged, or the signature will not match what the provider checks.

The spend note

The agent signs a SpendNote with EIP-712 (eth_signTypedData_v4). The vault keys the note's receipt by its full EIP-712 digest, so a note is bound to this chain, this vault, this payer, this agent, this provider and this amount, and it can be redeemed once.

name: Poncho
version: 1
chainId: 4663
verifyingContract: PonchoVault, listed under Addresses

Type string

SpendNote(address payer,address agent,address provider,uint256 serviceId,uint256 routeId,uint256 amount,uint256 nonce,uint64 deadline)

Typehash

0x63b4fe9ae6466a2a5023863a71a673905241a0740072403cf45824e59209d77f

Fields, in type order

payer address: whose balance is spent
agent address: the key that signs; may equal payer
provider address: who is paid, and the only address that may settle this note
serviceId uint256: registry service, for indexing only
routeId uint256: registry route, for indexing only
amount uint256: USDG atoms (6 dp)
nonce uint256: provider supplied, any value; the note hash is what is consumed
deadline uint64: unix seconds

SettleSkipped reasons

What trySettleMany writes in SettleSkipped(noteHash, payer, reason) when it leaves a note unsettled. Each reason is the check the strict path reverts on.

1 ZERO_AMOUNT: The note is for zero USDG.Strict path: ZeroAmount
2 AMOUNT_TOO_LARGE: That amount is above what the contract can hold.Strict path: AmountTooLarge
3 EXPIRED: That note is past its deadline. Ask the provider for a new quote.Strict path: NoteExpired
4 ALREADY_SETTLED: That note has already been redeemed.Strict path: NoteAlreadySettled
5 BAD_SIGNATURE: The signature does not match the agent key on the note.Strict path: BadSignature
6 NO_GRANT: That key has no grant on this balance.Strict path: NoGrant
7 GRANT_EXPIRED: That agent key has expired. Authorize it again.Strict path: GrantExpired
8 CAP_EXCEEDED: That is over what the key may spend this epoch.Strict path: CapExceeded
9 INSUFFICIENT_BALANCE: The payer balance is too low for that note.Strict path: InsufficientBalance

The payload a wallet signs

The X-Poncho-Note header

The agent retries the same request with one extra header. Its value is the base64url encoding, without padding, of this JSON:

Every note field is a string. Addresses are 0x hex; serviceId, routeId, amount, nonce and deadline are decimal.
The signature is 65 bytes of 0x hex, r then s then v, with v 27 or 28. A high s is refused, by the vault and by the kit.
base64url keeps it one token long, so no proxy or framework splits or rewrites it.

Checking a note

A provider checks a note before it serves the call, because nothing is paid until the note settles. Off chain, checkNote in js/chain/settle.js does the part that needs no network: the fields, the deadline, the price and the signature. The rest needs one read of the chain.

When the note is redeemed, the vault runs these checks, in this order, and the first one that fails decides the error:

The vault is not paused. EnforcedPause
The caller is the provider the note names, and that provider is not zero. NotProvider, ZeroAddress
The amount is above zero and fits in 128 bits. ZeroAmount, AmountTooLarge
The deadline has not passed. NoteExpired
The note has never settled, refunded ones included. NoteAlreadySettled
The signature is the agent's: ECDSA for a plain key, ERC-1271 when the agent is a contract. BadSignature
When the agent is not the payer: the payer granted the agent a key, the grant has not expired, and the amount fits in what is left of the key's cap this epoch. NoGrant, GrantExpired, CapExceeded
The payer's balance covers the amount. InsufficientBalance

A payer may withdraw between signing and settlement, and nothing stops it. settleMany then reverts as a whole; trySettleMany skips that note with a SettleSkipped reason and settles the rest. That is why a provider checks the balance and the cap before it serves, counts what it has served and not yet settled against them, and settles often.

Smart account agents. An agent with code signs through ERC-1271, which no off chain check can confirm. verifyNote answers null for those and never pretends. A provider that accepts them hashes the note with hashNote and asks the agent's isValidSignature with one eth_call.

Gate answers

What the provider kit's gate, poncho-gate.mjs on the sell page, answers besides the route's own response. A provider that writes its own gate is free to answer differently; a client should read the status and error first.

Discovery

Poncho describes itself to machines in plain files on this site, so an agent that has never seen it can find the chain, the vault, the note type and the 402 schema without reading a page written for people.

GET/.well-known/poncho.jsonThe protocol descriptor: the chain and its RPC, the settlement token, the four contract addresses and the deploy block, the EIP-712 domain and type, the header names, the 402 schema, the categories and where the ABIs live. The addresses are null until the contracts are deployed.
GET/protocol/abi/*.jsonThe ABI of each contract, as the compiler wrote it: vault, registry, staking, requests, and the ERC-20 surface.
GET/protocol/agentsPoncho written for an agent: the base URLs, the note, the header and the error codes on one page.
GET/llms.txtThe map of this site in plain text.

The descriptor, as this site serves it now

Open this to load it.

Site modules

The pages of this site sign and read with plain ES modules that also run in Node 22 with no dependencies. The kits fetch them into a poncho/js/ folder and import them, so a client, a gate and this site can never disagree about the protocol. Each file opens with the full list of what it exports.

JS/js/chain/settle.jsThe note: quoteToNote, typedData, hashNote, signNote, checkNote, verifyNote, parse402, quoteBody, encodeNoteHeader, decodeNoteHeader.
JS/js/chain/core.jsEvery read and every transaction builder: readService, readGrant, vaultBalanceOf, readReceipts, buildDeposit, buildGrant, buildTrySettleMany, explainRevert and the rest. setTransport(url) points it at any RPC.
JS/js/chain/abi.jsThe four ABIs as readable fragments, and the sentence behind every custom error.
JS/js/config.jsThe chain, the addresses, the protocol constants and the categories.
JS/js/pages/learn/kit/poncho-pay.mjsThe agent client of the quickstart: a fetch that pays a 402 within a ceiling, and a command line around it.
JS/js/pages/sell/kit/poncho-gate.mjsThe provider gate of the sell page: quotes, checks, banks, and poncho-settle.mjs redeems.

PonchoVault

Balances, agent keys, spend notes, receipts, provider earnings and the protocol fee.

The custody and settlement half of Poncho. A human deposits USDG once and authorizes an agent key with a cap per epoch and an expiry. The agent signs an EIP-712 SpendNote for a provider's quote; no transaction, no gas, no latency. The provider verifies the note off chain, serves the call, and later redeems banked notes with settle, settleMany or trySettleMany. USDG moves from the payer's balance to the provider's earnings, the protocol keeps a fee, and one Settled event carries everything the site indexes.

61 functions, 18 events, 34 errors in protocol/abi/vault.json.

Writes

Anyone may call these, subject to the checks each one lists.

depositpausable

deposit(uint256 amount)

Deposit amount USDG into your own balance. The balance that actually arrives is credited, so a token that takes a cut can never make this contract insolvent.

Reverts with EnforcedPause ReentrancyGuardReentrantCall SafeERC20FailedOperation TransferShortfall ZeroAmount

Selector0xb6b55f25

depositTopausable

depositTo(address payer, uint256 amount)

Deposit amount USDG into someone else's balance. Useful for topping up an agent's payer account from a treasury.

Reverts with EnforcedPause ReentrancyGuardReentrantCall SafeERC20FailedOperation TransferShortfall ZeroAddress ZeroAmount

Selector0xffaad6a5

withdraw

withdraw(uint256 amount)

Take amount USDG back out of your own balance. Never paused.

Reverts with InsufficientBalance ReentrancyGuardReentrantCall SafeERC20FailedOperation ZeroAmount

Selector0x2e1a7d4d

grantpausable

grant(
  address agent,
  uint128 capPerEpoch,
  uint32 epochLen,
  uint64 expiry
)

Let agent spend up to capPerEpoch USDG atoms of your balance in every window of epochLen seconds, until expiry. Resets what the key has spent and starts a fresh epoch now, so calling it again on a key hands that key a full cap at once: to renew a key, use extend. The windows are on a fixed grid, so across a window boundary a key can spend up to twice the cap within one epoch length. The key signs and never holds funds.

Reverts with BadEpochLength BadExpiry EnforcedPause SelfGrant ZeroAddress ZeroAmount

Selector0xc2079981

extendpausable

extend(address agent, uint64 expiry)

Move an existing grant's expiry, later or earlier, to any time in the future. The cap, the epoch length, the current window and what the key has spent in it are kept, so a renewal never resets the key's spend. A revoked or never made grant reverts NoGrant.

Reverts with BadExpiry EnforcedPause NoGrant

Selector0x59828aed

revoke

revoke(address agent)

Take an agent key's authority away. Never paused: a revoke must always go through.

Selector0x74a8f103

settlepausable

settle(SpendNote note, bytes sig)

Redeem one banked note. Only the provider the note names may call it.

Reverts with AmountTooLarge BadSignature CapExceeded EnforcedPause GrantExpired InsufficientBalance NoGrant NoteAlreadySettled NoteExpired NotProvider ReentrancyGuardReentrantCall ZeroAddress ZeroAmount

Selector0x6448d0b0

settleManypausable

settleMany(
  SpendNote[] notes,
  bytes[] sigs
)

Redeem many banked notes in one transaction. Every note must name the caller as its provider; one bad note reverts the whole batch and nothing is written.

Reverts with AmountTooLarge BadSignature BatchTooLarge CapExceeded EmptyBatch EnforcedPause GrantExpired InsufficientBalance LengthMismatch NoGrant NoteAlreadySettled NoteExpired NotProvider ReentrancyGuardReentrantCall ZeroAddress ZeroAmount

Selector0xf6cdb1bf

trySettleManypausable

trySettleMany(
  SpendNote[] notes,
  bytes[] sigs
) returns (
  uint256 settledMask,
  uint256 settledAmount
)

Redeem what can be redeemed of a batch. A note that fails a payer side check (its amount, its deadline, already settled, its signature, the agent's grant, cap or expiry, the payer's balance) is skipped with SettleSkipped and nothing is written for it; the rest settle exactly as settleMany would settle them. A note naming another provider, or none, still reverts the whole batch: that is the caller's bug, and skipping it would hide it.

An agent with code is asked through ERC-1271 with the gas that is left, exactly as settle asks it. One that burns all of it can still run the batch out of gas, so a provider that takes notes from smart account agents simulates the batch before it sends it.

Returns

settledMask uint256: Bit i is set when notes[i] settled.
settledAmount uint256: The gross USDG atoms settled, before the fee.

Reverts with BatchTooLarge EmptyBatch EnforcedPause LengthMismatch NotProvider ReentrancyGuardReentrantCall ZeroAddress

Selector0x31fbc2c0

refund

refund(bytes32 noteHash)

Give a settled note back, inside REFUND_WINDOW. Only the provider that was paid may call it. The payer is credited the gross amount; the net comes out of the provider's earnings and the fee out of feesAccrued, or out of the provider's earnings too when the fee has already been swept. Never paused.

Reverts with InsufficientEarnings NoteAlreadyRefunded NoteNotSettled NotProvider ReentrancyGuardReentrantCall RefundWindowClosed

Selector0x7249fbb6

withdrawEarnings

withdrawEarnings(uint256 amount)

Pull amount of your settled earnings. Never paused.

Reverts with InsufficientEarnings ReentrancyGuardReentrantCall SafeERC20FailedOperation ZeroAmount

Selector0x6e70096e

sweepFees

sweepFees()

Send the protocol fees to the sink. Anyone may call it. The sink's sync() is called only when the sink has code, and then inside a try, so a sink without code, without the function or with a reverting one cannot lock the fees here; the event says whether the callback went through. Never paused.

Reverts with FeeSinkNotSet NothingToSweep ReentrancyGuardReentrantCall SafeERC20FailedOperation

Selector0xd113b95c

Owner

Only the Poncho owner may call these.

setFeeBpsowner

setFeeBps(uint16 bps)

Set the protocol fee, at most MAX_FEE_BPS.

Reverts with FeeTooHigh OwnableUnauthorizedAccount

Selector0x023b1fc9

setFeeSinkowner

setFeeSink(address sink)

Point sweepFees at another sink. Zero is refused so fees always have somewhere to go.

Reverts with OwnableUnauthorizedAccount ZeroAddress

Selector0xda62e064

setTierSourceowner

setTierSource(address source)

Set the contract that answers provider fee discounts, or zero for no discounts.

Reverts with OwnableUnauthorizedAccount

Selector0xac7a37cb

pauseowner

pause()

Stop new deposits, grants and settlements. Withdrawals, revokes, refunds and sweeps never pause.

Reverts with EnforcedPause OwnableUnauthorizedAccount

Selector0x8456cb59

unpauseowner

unpause()

Let deposits, grants and settlements run again.

Reverts with ExpectedPause OwnableUnauthorizedAccount

Selector0x3f4ba83a

renounceOwnershipowner

renounceOwnership() view

Ownership is handed over in two steps or not at all.

Reverts with OwnableUnauthorizedAccount RenounceDisabled

Selector0x715018a6

acceptOwnershipowner

acceptOwnership()

The pending owner takes over.

Reverts with OwnableUnauthorizedAccount

Selector0x79ba5097

transferOwnershipowner

transferOwnership(address newOwner)

Start handing ownership to newOwner. Nothing changes until that address calls acceptOwnership.

Reverts with OwnableUnauthorizedAccount

Selector0xf2fde38b

Reads

feeBps

feeBps() view returns (uint16)

The protocol fee on every settlement, in basis points.

Selector0x24a9d853

feeSink

feeSink() view returns (address)

Where sweepFees sends the fees (PonchoStaking after the deploy wiring).

Selector0x4b38474d

tierSource

tierSource() view returns (address)

The contract asked for a provider's fee discount, or zero for no discounts.

Selector0x6738c1b1

feesAccrued

feesAccrued() view returns (uint256)

Fees taken and not yet swept.

Selector0x94db0595

balanceOf

balanceOf(
  address
) view returns (uint256)

Deposited USDG, spendable by the payer and by its live agent keys.

Selector0x70a08231

grantOf

grantOf(
  address,
  address
) view returns (
  uint128 capPerEpoch,
  uint128 spent,
  uint32 epochLen,
  uint64 epochEnds,
  uint64 expiry
)

A payer's grant to one agent. capPerEpoch == 0 && expiry == 0 means no grant; a payer always has an implicit unlimited grant to itself.

Selector0xb98e8226

receiptOf

receiptOf(
  bytes32
) view returns (
  address payer,
  address provider,
  uint128 amount,
  uint128 fee,
  uint64 settledAt,
  bool refunded
)

Every settled note, by its EIP-712 digest.

Selector0x72a41fdd

earningsOf

earningsOf(
  address
) view returns (uint256)

A provider's unclaimed earnings, pulled with withdrawEarnings.

Selector0x8df08bd4