x402-credits / tree / README.md · raw (this view has old GitHub links rewritten for the mirror; raw is byte-exact)

YourAITools Credits

Prepaid credits for the YourAITools x402 agent APIs. Pay once over x402, get an API key, then call any of the tools with Authorization: Bearer <key>. Each call debits its normal per-call price, so there's no on-chain payment per call.

Live: https://api.youraitools.co/credits/ (also https://credits.agentgate.workers.dev)

Route	Price	What you get
`GET\\|POST /v1/pack/1`	$1 USDC	new key with $1.00 of credits
`GET\\|POST /v1/pack/5`	$5 USDC	new key with $5.50 of credits (10% bonus)
`GET\\|POST /v1/pack/sample`	$0.005 USDC	new key with $0.005 of credits (try the whole flow)
`GET\\|POST /v1/topup/1`, `/v1/topup/5`	$1 / $5	add $1.00 / $5.50 to an existing key (send the key)
`GET /v1/balance`	free	balance, spend per tool, recent calls (send the key)
`POST /v1/key/rotate`	free	move the balance to a new key; the old key stops working
`GET /v1/preview?pack=5`, `/v1/prices`	free	what a pack buys at today's prices
`POST /mcp`	free	remote MCP: `credits_quote`, `credits_balance`

You can pay in USDC on Base, Polygon, Arbitrum One or Solana with x402 v2 (PAYMENT-SIGNATURE), or on Base with v1 (X-PAYMENT). A pack is settled only when its key is delivered: if settlement fails, the key is never shown and the account is deleted.

Using a key

curl -s -H "Authorization: Bearer $KEY" "https://api.youraitools.co/payguard/v1/address?address=0x098B716B8Aaf21512996dC57EB0615e2383E2f96"
# response headers: X-Credits-Charged: 0.001000, X-Credits-Remaining: 0.999000, X-Credits-Ref: r_...

Accepted by every paid route of AgentGate, WebRead, InjectScan, DomainCheck, PayGuard, PkgGuard, StackDetect, TokenVerdict and SignCheck. The same key also works as X-Credits-Key or X-Credit-Token.
A failed call (HTTP 400 or higher) is not charged; its debit goes back to the balance.
When the balance is too low, the tool sends its normal x402 402 (the PAYMENT-REQUIRED terms are unchanged), plus X-Credits-Error: insufficient_balance, X-Credits-Topup and a credits hint in the JSON body.
Without a key nothing changes. The x402 terms on every route are byte-identical to before. A HEAD request never spends credits.

How it works

Accounts: each key has its own SQLite-backed Durable Object (CreditAccount), named by the SHA-256 of the key. The key itself is never stored.
Debits: a debit is a single Durable Object event (check plus write, protected by input gates), so concurrent calls can't overspend. Tests fire 200 concurrent debits.
Tool side: the tools call the CreditsGate RPC entrypoint over a service binding. The tool-side code is credits-gate.js, a drop-in wrapper around @x402/hono's paymentMiddleware.
Top-ups: a top-up is held as pending inside the paid request and committed only after the x402 settlement succeeds.
Storage: no KV writes. Counters use the same batched StatsCounter Durable Object as the tools.

Terms

Credits are prepaid usage of the YourAITools APIs only, priced in USD at each route's normal per-call price. They are not money and not a token or investment. They have no cash value, can't be withdrawn and are not refundable. Whoever holds the key can spend the credits.

MIT licensed. npm test (node --test) · wrangler deploy.

agentgate-source: code mirror on Cloudflare Pages. All repos