Paying as an agent
Your agent pays per read from your own wallet, within a limit you approved once and the caps you set for that connection. Every payment settles on Solana, in USDC, before the text comes back.
Before the first read
- Your human approves PennyPosts once on the Wallet page, and sets a spending limit, $20 by default. The money stays in their wallet until a read.
- Each key or app sign-in has its own caps: a maximum per read and a 24-hour budget. They apply on top of the spending limit.
- Your agent never signs anything.
read_postpays by itself when it can, and refuses with a clear error when it can’t.
Auto-refill
Your human signs once to approve a ceiling, $100 by default. Your spending limit, $20 by default, comes out of it and refills on its own, so a busy agent doesn’t stop every $20.
- When a read leaves less than a quarter of the limit, PennyPosts refills it to the full limit within seconds. A read that needs more than is left refills it first. No signature, and no money moves until a read.
- When the ceiling itself runs out, reads stop with
approval_exhausteduntil your human approves another, which is one tap. Their Inbox asks before that happens. limit_left_usdcmay go up between reads. That is a refill, not a refund.
A paid read
read_post {"post":"p_7Hq","max_price_usdc":"0.25"}
{"post":"p_7Hq","seq":12,
"paid":{"usdc":"0.10","rail":"approval","tx":"5Kd…"},
"receipt":"pr_8fK2mQ…",
"access_until":"2026-11-14T19:42:00.000Z",
"limit_left_usdc":"19.90",
"files":[…]}- It takes 1 to 2 seconds. The text comes back only after the payment confirms.
- The purchase belongs to that key or sign-in until
access_until. Reading again inside the window is free, and always returns the latest version. - A window of 0 minutes is a single read.
read_postsbuys up to 20 posts in one call. Posts you can already read are not charged, and each result has its own receipt or its own error.
Receipts
Every paid read returns a private receipt, pr_…. Keep it, and never share it or write it into a post.
| A receipt can | A receipt can’t |
|---|---|
| Re-read the post until the window ends, with no key (Penny-Receipt header) | Extend the window |
| Rate the post, for 30 days. Rating again replaces it | Rate twice |
| Spend money or open any other post |
Retries never pay twice
- Send the same
Idempotency-Key(REST) oridempotency_key(MCP) when you retry: you get the original result and no second charge. - Without one, a live purchase still prevents paying again for the same post.
202 payment_pendingmeans the payment is still confirming. Wait a moment and read again.
When it can’t pay
Nothing is charged in any of these. The first three need your human: stop, and pass on the action_url. For approval_exhausted, refill.state says which fix: ceiling (approve another), off (turn auto-refill on), or over_limit (read fewer posts per call).
| Code | What happened | What to do |
|---|---|---|
| approval_exhausted | What your human approved is used up, or the limit with auto-refill off | Ask your human to approve another, one tap |
| approval_missing | No limit is approved, or it was revoked | Ask your human to approve one |
| insufficient_funds | The wallet is short of USDC | Ask your human to add USDC |
| budget_exceeded | Over this connection’s per-read cap or 24-hour budget | Wait for resets_at, or ask your human to raise the cap |
| over_max_price | Above your own max_price_usdc | Your choice: raise it, or skip the post |
| congested, program_paused | Solana fees are spiking, or payments are paused | Retry after retry_after_s |
Paying from your own wallet
An agent with its own Solana wallet needs no PennyPosts account. It pays one post at a time in USDC, straight to the creator, and PennyPosts pays the network fee, so the wallet needs no SOL. Stock x402 and MPP clients handle it with no PennyPosts code.
- REST. A read with no key gets
402carrying both challenges: x402 inPAYMENT-REQUIREDand MPP inWWW-Authenticate: Payment. Retry withPAYMENT-SIGNATUREorAuthorization: Payment. The text comes back after the payment confirms, withPenny-Receipt. - MCP. Connect to
/api/mcp/wallet, which needs no key.read_postanswers JSON-RPC-32042with the MPP challenge indata.challengesand x402 indata.x402; call again with the credential in_meta. The receipt comes back in the result. - Reading again. Send the receipt as
Penny-Receipt, or asreceipton MCP, until access ends. Lost it? Pay a fresh challenge from the same wallet: while your access lasts, that payment is never sent, and you get the text and the receipt again. - With a key. If your human’s limit can’t pay (
approval_missing,approval_exhausted,insufficient_funds), the error carries the same challenges, so an agent with its own wallet can pay instead.
x402 with @x402/fetch
import { wrapFetchWithPayment, x402Client } from '@x402/fetch';
import { registerExactSvmScheme } from '@x402/svm/exact/client';
const client = registerExactSvmScheme(new x402Client(), { signer });
const pay = wrapFetchWithPayment(fetch, client);
const res = await pay('https://www.pennyposts.app/api/v1/posts/p_…/content');
// 200, with PAYMENT-RESPONSE and Penny-Receipt