Concepts

The 402 gateway

Each item a seller publishes lives at https://api.v4.cryptocadet.app/v4/g/<handle>/<slug>, where the handle is the seller's public name and the slug names the item. A request with no payment gets 402 Payment Required and a JSON body with the price and the accepted ways to pay. A request that carries a valid payment gets the item.

An item is one of two kinds:

• Hosted: the seller uploads the content (up to 200 KB) and CryptoCadet serves it. Read it with GET.
• Proxy: the seller gives an HTTPS origin URL. After payment, the gateway forwards the request (method, body, sub-path and query string) to that origin and streams the answer back. Each forwarded request is signed so the origin can check it came through CryptoCadet.

And it has one of three visibilities: paid (the default), free (served to anyone, no payment), or private (only people the seller shares it with, see below). Prices are set in US dollars and can go down to a millionth of a dollar.

Two payment rails

cryptocadet fetch tries credits first when you have an agent token, and falls back to USDC if credits are refused (for example, not enough balance) and the item accepts USDC. It only ever sends the agent token to the CryptoCadet server it is configured for, never to another site that asks for it.

The agent wallet and local policy

cryptocadet init creates a dedicated agent wallet on Base for your agent to spend from. Treat it as a float: keep a working amount there and top it up from your main wallet yourself. The CLI never asks for your main wallet's key, and nothing moves money out of your main wallet automatically.

The agent key is encrypted on disk (AES-256-GCM) and its data key is in your OS keychain. Once unlocked, the key is held only in the CLI's memory, never written to disk in plain form. Anything that can read that process's memory while it runs could obtain the key, which is why the float should stay small: the most you can lose is what is in the agent wallet.

Every USDC payment is checked against ~/.cryptocadet/policy.json, your local policy. It is the only spending control on this rail, and it fails closed: if anything is missing or unreadable, the payment is refused. The starting policy:

The agent can't pay an amount or address it makes up: the CLI pays only server-signed quotes, checks the signature against a key pinned at init, and re-checks every field against your policy before it signs. Change the policy with policy:set and allowlist:add; see Buying.

Agent tokens and caps

An agent token (it starts with ccx_agent_) lets an agent spend your card credits at gateway URLs. It can't read or change your account. Each token has its own limits, enforced by the server:

• Per-call cap: the most it pays for one request.
• Daily cap: the most it spends in any rolling 24 hours.
• Allowed sellers: optionally, the only seller handles it may buy from.

The raw token is shown once, when it is created. The CLI puts it straight into the OS keychain and never prints it. You can revoke a token at any time and it stops working immediately.

Private items and grants

A seller can make an item private and share it with specific people by email. Each share (a grant) is one of two modes:

• Unlock: the buyer pays the price once, then reads it free.
• Per query: the buyer pays the price on every request.

Private items are paid with card credits only. The buyer's agent token must belong to the CryptoCadet account with the email the item was shared with.

Fees and payouts

CryptoCadet charges a 3% fee on each paid request, on either rail.

• USDC payments go through the CryptoCadetRouter contract on Base (0xFFE91f1582080c85f7651fA32de2186df1b9343b). In one transaction it sends 97% to the seller's payout wallet and the 3% fee to CryptoCadet. CryptoCadet never holds these funds.
• Card-credit payments add 97% of the price to the seller's earnings balance. Earnings are paid out in USDC on Base to the seller's payout address once they reach the $10 payout minimum.

If a proxy item's origin fails (it can't be reached, or answers with a 5xx error), the buyer gets 502 and a card-credit charge is normally refunded automatically. USDC payments are on-chain and can't be refunded by CryptoCadet.