Poncho docs

Start here#

Poncho has two sides. A payer deposits USDG into the vault once and lets an agent key spend it, within a cap per epoch that the vault enforces. A provider lists routes with a price, answers an unpaid call with a quote, and redeems the notes it is paid with on Robinhood Chain. One balance pays every route that is listed.

What you need:

• A wallet on Robinhood Chain with USDG to deposit and a little ETH for gas. The balance page can swap ETH to USDG for you.
• For the command line: Node 22 or later, cast from Foundry (it signs with your keystore, so no file here ever sees a key), curl and jq.

Network

Robinhood Chain, chain id 4663 (0x1237)

Gas

ETH. Blocks come every 0.1 s.

Settlement

USDG, 6 decimals: 1000000 atoms is 1 USDG

RPC

https://rpc.mainnet.chain.robinhood.com

Explorer

robinhoodchain.blockscout.com

Addresses

API reference and /.well-known/poncho.json

Every command below reads the contract addresses from that descriptor, so none of them carries an address you could mistype. Set the shell up once:

The contracts are not on Robinhood Chain yet, so the descriptor's addresses are null and these commands have nothing to talk to. They are the commands you will run at launch; this page fills in the live numbers then.

01Fund a balance#

The balance lives in PonchoVault and belongs to the wallet that deposits it. Every key you authorize spends from it, and you can withdraw what is left at any time: withdrawals never pause.

In the browser. Open your balance page, connect, enter an amount, approve USDG for the vault and deposit. The page shows your allowance before you sign, and can swap ETH to USDG on the way.

Open your balance

From the command line, with the wallet in a Foundry keystore:

The vault credits what actually arrives, and the Deposited event says how much. Anyone can also fund someone else's balance with depositTo, which is how a team tops up an agent's payer account.

02Authorize an agent key#

An agent key is an address that signs notes on your balance. It holds no USDG and sends no transaction, so losing it costs at most what it may still spend. You give it three limits, and the vault checks all three on every note it settles:

• A cap per epoch, in USDG atoms: the most the key may spend in one window.
• An epoch length, in seconds: how long each window lasts, from to . When a window ends the key's spend starts again from zero.
• An expiry, in unix seconds: after it the vault accepts nothing the key signs.

Granting the same key again replaces its limits and starts a fresh epoch. Revoking deletes the grant at once, and revoke never pauses. Your own wallet needs no grant: it can sign notes on its own balance with no cap at all, which is fine for trying things and not what you give a running agent.

In the browser, under Agent keys on your balance page. From the command line:

03Your first paid call#

poncho-pay.mjs is the agent's side of the protocol in one file: a fetch that answers a 402 by signing one note within a ceiling you set, and a command line around it. It has no dependencies. It imports the same modules this site signs with, so the note it builds is the note the vault redeems.

Once, in an empty folder:

Then pay for a call. ROUTE is the full address of a route: its service endpoint followed by its path, as the route's page on the marketplace shows it.

Here is what happens in that one command:

1. It asks the route once, with no note. A paid route answers 402 with a quote.
2. It checks the quote: poncho/1, Robinhood Chain, the Poncho vault, an amount under --max, a deadline within a day, and, for a listed service, that the provider owns it and the amount is the price the registry lists.
3. It signs a SpendNote for exactly that quote with cast. No transaction and no gas.
4. It asks again with the note in X-Poncho-Note, prints the answer, and prints what it paid and the note's hash.

Nothing leaves your balance yet. The note is a promise the provider redeems later, many at once. When it does, the Settled event is the receipt: the note shows on your balance page and on Ponchoscan. Anything the checks refuse is never signed, and the command exits with status 2.

In your own agent, use it as a module:

An agent that signs with something other than cast passes its own sign(typedData): a hardware wallet, a smart account, or a signer from a library it already uses. The payload is the standard eth_signTypedData_v4 object, documented in the API reference.

04Take payment#

The other direction. A provider lists what it sells, answers unpaid calls with a quote, and collects its notes on chain whenever it likes. No signup, no API keys to hand out, and one listing reaches every agent with a Poncho balance.

List a service

On the sell page, register a service with a slug, a name, a one line summary, its https endpoint, a docs link and a category, then add routes: a method, a path and a price in USDG. Listing is open to anyone and the listing fee is . Prices change with one transaction, and a route can be switched off without deleting it.

Put the gate in front

poncho-gate.mjs sits in front of any Node HTTP handler. It answers 402 with a real quote, checks the note it gets back against the chain, banks it and lets the call through. Fetch the kit:

Start it with your service id, the number in your service's /service/ address:

Every route your service lists now answers 402 until it is paid; paths it does not list pass straight through. Try one with the paying command above.

Settle and get paid

Banked notes are promises until you redeem them. poncho-settle.mjs puts every note that can still settle into one transaction and leaves the rest in the bank for the next run, so one payer who withdrew cannot sink the batch. Run it by hand or from cron, well inside the quote's deadline:

Settled USDG becomes your earnings in the vault, less the protocol fee of . Withdraw them on the sell page, any time. You can give a settled note back with refund for after it settles: the payer is credited in full. The whole kit, its 402 body and every answer it gives are on the sell page.

Fees and limits#

What the contracts charge and allow right now, read from Robinhood Chain when you opened this page.

Read from the Poncho contracts on Robinhood Chain.

Glossary#

Balance

USDG deposited in PonchoVault. It belongs to the payer, and every key the payer authorizes spends from it.

Payer

The wallet whose balance a note spends.

Agent key

An address that signs notes on a payer's balance. It never holds USDG. The payer's own wallet is an agent key with no cap.

Grant

The limits a payer gives one agent key: a cap per epoch, an epoch length and an expiry.

Epoch

The window a cap applies to. When it ends, the key's spend starts again from zero.

Quote

What a provider answers an unpaid call with: HTTP 402 and a JSON body naming the provider, the service, the route, the amount, a nonce and a deadline.

SpendNote

The EIP-712 message an agent key signs for one quote. Free to sign, and redeemable once, by the provider it names, before its deadline.

Bank

The notes a provider has served and not yet redeemed.

Settle

Redeem notes on chain. USDG moves from the payer's balance to the provider's earnings, less the protocol fee.

Receipt

The Settled event and the vault's record of a note, keyed by the note's hash. Anyone can read both.

Refund

A provider giving a settled note back inside the refund window. The payer gets the full amount back.

Request

A bounty in USDG escrow for a route that does not exist yet. Providers propose a service and the requester awards one.