x402 payments that stay inside a budget
Let agents pay per API call over x402 while caps stop runaway spend.
Set a budget
Read the price before signing
Send an unpaid request to SingIt Ask. The HTTP 402 response contains a PAYMENT-REQUIRED header with base64 JSON for x402 v2. Read the offers before signing one. The offer's per-request ceiling is a per-call cap you can inspect in the 402. It does not by itself create a daily budget or restrict later requests that your wallet chooses to sign.
The accepts list puts upto first, Base then Solana, followed by exact on both networks. Select one offer and retry the same request with PAYMENT-SIGNATURE. A successful HTTP 200 includes choices[0].message.content and billing.totalAtomic. Keep the settled amount for your own accounting instead of treating the initial ceiling as the final bill.
upto and exact are different commitments
With upto, you sign a ceiling. The server settles the actual provider cost plus markup and the settlement fee, never more than that ceiling. The answer normally costs less than the reference ceiling. With exact, the price is flat and there is no refund. Both schemes expose a price before signing, but only upto settles against actual usage. Use the live 402 for the request you are about to send.
Read a Base limiter in the 402
On an unpaid request, send the header X-SingIt-Limiter: 0xYourLimiter with your AgentAllowance address on Base. The 402 carries X-SingIt-Spend-Limit. It reports what the limiter allows right now, including its paused and expired state, remaining daily amount and allowance. The response also reports whether each Base offer fits. Solana offers are not checked against this Base limiter.
This is a reading of the Base limiter, not a new payment authorization or an extra daily cap for the caller. The read is cached for 15 seconds and does not read the owner's USDC balance. Treat it as information before signing, rather than a reservation of funds. An invalid limiter returns an error instead of usable limit figures.
Read the settled receipt
Every settled answer carries X-SingIt-Receipt. It records the charged amount, ceiling, network and scheme. When the limiter header was supplied, it also includes limit figures read just before the answer. An unsettled answer has no settled receipt. The SingIt app also shows purchases and receipts for its own agent's activity.
Know the boundary of the budget
A wallet that signs x402 payments by itself is not limited by AgentAllowance. The limiter applies to purchases made through SingIt's own agent in the SingIt app. Reading a limiter in the 402 does not route an independent wallet's payment through that contract. Configure the signing client separately and review its enforcement model.
Client-side caps in SDKs and the elizaOS plugin live in the client process. They are not on-chain and are only as strong as that process. The @singitai/plugin-singit paid-chat action pays on Base. Its per-call and per-day caps are held in the plugin's memory: in-process, reset on restart, not on-chain, and not enforced by SingIt's servers.
Solana has a separate allowance mechanism
On Solana, the owner's wallet approves an SPL delegate total on its USDC account. The chain enforces that total and one Revoke ends it. The daily limit, the per-purchase limit and the expiry are enforced by SingIt's server, not on-chain. A pause refuses new purchases without removing the approval. Only a new owner-signed approval lifts it; a purchase already reserved may still settle.
FAQ
What does upto authorize?
- A ceiling. The server settles actual cost plus markup and the settlement fee, never more than the ceiling.
Does exact refund unused tokens?
- No. It is a flat price with no refund.
Does reading a limiter restrict my independent wallet?
- No. AgentAllowance applies to purchases through SingIt's own agent in the SingIt app.
Are the plugin's caps on-chain?
- No. They live in the plugin's memory, reset on restart, and are not enforced by SingIt's servers.