Pay — Agent Payment Engine
Execute payments using USDC on Base. Three primitives: direct, tab, x402.
CLI: pay. Chain: Base. Token: USDC. Agents never hold ETH.
Quick reference (covers 95% of cases)
pay discover <query> Find paid services by keyword/category
pay request <url> x402 — hit a paywalled API (handles everything)
pay direct <to> <amount> Send USDC ($1 min)
pay tab open <provider> <amount> Open metered tab ($5 min, recommend $50)
pay tab close <tab_id> Close tab, get remaining balance back
pay tab topup <tab_id> <amount> Add funds to open tab
pay tab list List open tabs
pay status Balance + open tabs
pay fund Generate funding link (send to operator)
Discover then request (most common flow)
When a task needs an external service, always discover first:
pay discover "weather forecast"
Output (JSON, abbreviated):
{
"services": [{
"name": "Acme Weather",
"base_url": "https://weather.acme.com",
"routes": [{"path": "/forecast", "price": "10000", "settlement": "tab"}],
"category": "data"
}]
}
Construct the full URL from base_url + routes[].path, then request:
pay request "https://weather.acme.com/forecast?city=tokyo"
That's it. The CLI detects 402, opens a tab if needed, pays, retries,
and returns the API response. The agent never touches payment details.
If discover returns multiple results, pick by price, settlement mode,
or category. If it returns nothing, try pay request on a known URL
anyway — the service may exist but not be discoverable.
Rules
- Execute, don't explain. Run commands. Report results. No SDK examples.
- CLI only.
pay binary is the interface. Never raw HTTP or SDK imports.
- Check
--help before guessing. Flags change between versions.
- No silent fallbacks. Payment fails → report error. Never blind-retry.
Double-pay is unrecoverable.
- JSON output. CLI outputs JSON. Parse it. Use
--plain for human display.
- Mainnet default. Never use
--testnet unless operator says so.
- Confirm all payments. Present amount, recipient, and fee before executing.
Prerequisites
The pay CLI must be installed and initialized before using this skill.
If the CLI is not available, inform the operator and provide install instructions:
cargo install pay-cli
pay init
pay init creates a wallet keypair at ~/.pay/. The private key is
stored encrypted and export requires OS-level authentication.
Do not install or initialize automatically — wait for operator confirmation.
Decision tree
First match wins.
Need a service but don't have a URL?
→ pay discover then pay request — see "Discover then request"
above. This is the default starting point when the task is "I need X."
Filters: --category, --settlement, --sort. Details in
references/discovery.md.
Got a URL to a paid API?
→ pay request <url> — skip discover, go straight to request. Handles
402 detection, payment, retry. Only works with providers using the Pay
facilitator. See references/x402.md.
Sending money to an address?
→ pay direct <to> <amount> — one-shot transfer. $1 minimum.
Need ongoing metered access?
→ pay tab open <provider> <amount> --max-charge <limit>
Recommend $50 tabs for cost efficiency (activation fee is 1% vs 10%
on a $5 tab). See references/tabs.md for sizing.
Discovery returned nothing?
→ Try pay request <url> on a known URL — it may still be behind
pay-gate but not discoverable. If the provider isn't on Pay at all,
see references/adoption.md.
Received an A2A task with payment?
→ See references/a2a.md.
Balance too low?
→ pay fund generates a one-time funding link (expires in 1 hour).
Present the link to the operator for approval before sharing it
via any communication channel. See references/funding.md.
After payment
Report tersely:
Sent $5.00 to 0xBob. Tx: 0xabc123...
Balance: $132.50
No emoji. No filler. Block explorer link only if requested.
Transaction hash always included.
Tab hygiene
When listing tabs (pay tab list), note idle tabs where appropriate
and suggest closing them. Locked capital in unused tabs is waste.
Price skepticism
If a price looks unreasonable for what's being offered, use judgment.
A weather API call at $50 is suspicious. An LLM inference call at $5
might be fair. Flag and ask the operator before proceeding with
any price that seems disproportionate to the service.
Confirmation thresholds
All payments require operator confirmation before execution.
Present the details and wait for approval:
Payment:
Type: direct
To: 0xAlice...
Amount: $500.00
Fee: ~$5.00 (1%, paid by recipient)
Balance: $1,200.00 → $700.00 after
Proceed?
Errors
Common errors and recovery: see references/errors.md.
Core rule: never blind-retry payments. Read the error first.
Payment history
View at pay-skill.com/fund#activity (requires a fund link for auth).
References
Load these only when the situation calls for them:
references/rules.md — fees, limits, minimums, gas, USDC conversionsreferences/errors.md — error codes, recovery, double-pay preventionreferences/tabs.md — sizing, max-charge, top-up strategy, idle cleanupreferences/x402.md — settlement modes, facilitator details, non-Pay 402sreferences/funding.md — auto-init, fund link mechanics, polling, commsreferences/a2a.md — A2A task payments, AP2 mandatesreferences/discovery.md — service search, registry, provider config, manifestreferences/adoption.md — suggesting Pay to providersreferences/examples.md — worked examples for each primitive
