Guides
Buying
Give your agent a budget, decide who it may pay, and let it pay per request.
Card credits or your own USDC
| Card credits | Your own USDC | |
|---|---|---|
| You need | A card | USDC and a little ETH on Base |
| Limits | Per-token caps, enforced by the server | Your local policy, enforced on your machine |
| Sellers | Any, or a list of handles per token | Each seller allowlisted once |
| Private items | Yes, if shared with your email | No |
| Refund if the seller's API fails | Normally automatic | No, on-chain payments are final |
You can set up both. cryptocadet fetch tries credits first and falls back to USDC.
Card credits
cryptocadet credits:buy --usd 20
This prints a Stripe Checkout link (pay) and a sessionId. Open the link and pay. Top-ups are whole cents between $5 and $1,000. Your balance is credited as soon as Stripe confirms the payment; if it hasn't shown up after you paid, settle it by hand:
cryptocadet credits:verify --session <sessionId>
cryptocadet credits:show
You get a receipt email for each top-up, and one warning email when your balance drops below $1 or when an agent is refused for lack of credits. That warning is sent again only after your next top-up.
Agent tokens
An agent token lets the agent on this machine spend your credits, within limits you choose:
cryptocadet agent-token:create --name research-agent --per-call-usd 0.50 --daily-usd 10 --sellers acme,datahub
--per-call-usd: the most it may pay for one request.--daily-usd: the most it may spend in any rolling 24 hours.--sellers: optional, comma-separated seller handles it may buy from. Leave it out to allow any seller.
Each cap is optional; a cap you leave out doesn't apply. The token goes straight into the OS keychain and is never printed. A machine holds one token at a time, so creating a new one replaces the stored one (the old token keeps working until you revoke it).
cryptocadet agent-token:list # all your tokens, and whether this machine has one
cryptocadet agent-token:revoke --id <id> # stop a token immediately, on every machine
cryptocadet agent-token:clear # forget the token on this machine only
Spending policy for USDC
USDC payments are limited by ~/.cryptocadet/policy.json. It starts at $1 per payment and $5 per day (see Concepts). View and change it:
cryptocadet policy:show
cryptocadet policy:set --kind perTx --token 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 --usdc 2
cryptocadet policy:set --kind daily --token 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 --usdc 20
--usdc takes dollars. --amount takes base units instead, where --amount 50 means $0.00005, not $50.
Allowlisting sellers
The wallet pays only sellers you have allowlisted, by their payout address. When fetch meets a new seller it stops and prints the exact command:
cryptocadet allowlist:add --kind recipient --address 0xSellerPayoutAddress
cryptocadet allowlist:remove --kind recipient --address 0xSellerPayoutAddress
The address is the payTo field of the item's 402 response. Card credits don't use this list; restrict them per token with --sellers.
Fetching
cryptocadet fetch https://api.v4.cryptocadet.app/v4/g/acme/market-brief
cryptocadet fetch https://api.v4.cryptocadet.app/v4/g/acme/quotes/latest \
--method POST --data '{"symbol":"ETH"}' --header 'Content-Type: application/json'
--header can be repeated. URLs must be https. You can't set Authorization, X-PAYMENT or X-CryptoCadet-Agent yourself; the payment flow sets them. A successful fetch prints:
{
"status": 200,
"paid": true,
"rail": "credits",
"charged": "50000",
"contentType": "text/markdown; charset=utf-8",
"body": "…",
"truncated": false
}
charged is in micro-dollars ($0.05 here). A USDC payment shows "rail": "usdc" with a quoteId and txHash instead. A body over 64 KB is cut off in this output and truncated is true.
Approvals
To approve larger USDC payments yourself, set a threshold:
cryptocadet policy:set --kind requireHumanAbove --token 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 --usdc 0.50
A payment above it is held with Confirm it: re-run with --approve. Re-run the same command with --approve to pay it. Approval only lifts the threshold: the caps and the seller allowlist still apply. There is no threshold by default.
Looking after the wallet
cryptocadet wallet:show: the agent address, its USDC and ETH balances, and a warning if ETH is low.cryptocadet topup:request <token>=<target>: works out how much to send to bring a token up to a target balance (in base units). You make the transfer yourself.cryptocadet sweep --to <address>: move everything out of the agent wallet.cryptocadet rotate: replace the agent key. It asks before it starts, and offers to move the old wallet's funds first. The old key is destroyed.