@ucash/agents

Non-custodial HTTP-402 payments for AI agents.

Agents sell priced resources over a single HTTP 402 challenge - buyers pay direct to the seller's own wallet (on-chain, any coin) or via card (the seller's own Stripe). The platform never holds funds. Multi-coin: BTC (+Lightning), ETH + all ERC-20s, USDT, USDC, Solana, Tron, XRP, Monero, UCASH, custom tokens.

agents.u.cash is the interaction layer (API/SDK/MCP); payments happen on pay.u.cash. Every resource returns a checkout_url (/checkout/<enc>?cloud=<token>) and every payment request returns a url (/id/<enc>) - both are the 402 door on pay.u.cash. A human opens the HTML checkout; an agent fetches ?agent=1 for the JSON manifest (HTTP 402 + accepts[]); an x402 client pays with an X-PAYMENT header. The agents.u.cash /r/{res_id} link is a back-compat alias of /checkout/ (same engine, same challenges).

Exact amount vs dust. The platform matches the buyer's on-chain transfer to the exact amount + receive address it issued. Save 3+ addresses for a coin (comma-separated: POST /v1/wallets {asset:'ucash', address:'0xaaa...,0xbbb...,0xccc...'}) and each buyer gets a unique address, so the door demands the exact amount (500.00000000). With one address (reused), the door adds a tiny dust in the last decimals (500.00004180) so two concurrent same-amount payments to that address stay distinguishable - the buyer pays effectively the listed amount. For a literal token price (asset + asset_amount), save 3+ addresses for exact mode.

Live: agents.u.cash · OpenAPI spec · llms.txt · MCP page

What's in this repo

Path	What
sdk/javascript/	Zero-dependency JS/Node SDK (npm: @ucash/agents)
sdk/python/	Zero-dependency Python SDK (PyPI: agents-u-cash)
mcp/	stdio MCP server (Claude Desktop / any MCP client) + README
api/openapi.json	OpenAPI 3.1 spec (also served live at agents.u.cash/openapi.json)

Quickstart (60 seconds)

# 1. Sign up (wallet-first; no email loop)
curl -X POST https://agents.u.cash/v1/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"me@agent.dev","password":"longpass"}'
# -> {"response":{"api_key":"…","activated":false}}  # works immediately at $0

# 2. (Optional) Top up >= $1 for platform credit (or verify your email for free starter credit)
curl -X POST https://agents.u.cash/v1/top-up \
  -H 'X-Api-Key: $KEY' -d '{"amount":1}'

# 3. Set your receive address (where buyers pay you)
curl -X POST https://agents.u.cash/v1/wallets \
  -H 'X-Api-Key: $KEY' -d '{"asset":"btc","address":"bc1q…"}'

# 4. Create a priced resource
curl -X POST https://agents.u.cash/v1/resources \
  -H 'X-Api-Key: $KEY' -d '{"amount":0.05}'
# -> {"response":{"res_id":"res_…","checkout_url":"https://pay.u.cash/checkout/<enc>?cloud=<token>"}}
# Share the checkout_url (the pay.u.cash buyer door). https://agents.u.cash/r/{res_id} is a back-compat alias.

# 5. (Optional) One-off payment request instead of a persistent resource:
curl -X POST https://agents.u.cash/v1/payment-requests \
  -H 'X-Api-Key: $KEY' -d '{"amount":5,"expiry":"24h"}'
# -> {"response":{"url":"https://pay.u.cash/id/<enc>", ...}}  # closes when paid or after expiry

SDKs

JavaScript

npm install @ucash/agents

import { AgentsUCash } from '@ucash/agents';
const agent = new AgentsUCash({ apiKey: 'your_key' });
await agent.setWallet('btc', 'bc1q…');
const res = await agent.createResource({ amount: 0.05 });  // res.checkout_url = pay.u.cash buyer door
await agent.createPaymentRequest({ amount: 5, expiry: '24h' }); // one-off -> {url: pay.u.cash /id/...}

Python

pip install agents-u-cash

from agents_u_cash import AgentsUCash
agent = AgentsUCash(api_key='your_key')
agent.set_wallet('btc', 'bc1q…')
res = agent.create_resource(amount=0.05)  # res['checkout_url'] = pay.u.cash buyer door
agent.create_payment_request(amount=5, expiry='24h')  # one-off -> {'url': pay.u.cash /id/...}

MCP server (Claude Desktop)

See mcp/README.md for setup. Tools include uxc_get_agent, uxc_set_wallet, uxc_create_resource, uxc_list_resources, uxc_create_payment_request, uxc_list_payment_requests, uxc_create_challenge, uxc_get_settlements, uxc_view_door, uxc_verify_payment.

Subagents (scoped RBAC keys)

Delegate a LIMITED, scoped sa_ API key to another automated principal. A subagent authenticates against your tenant with a staff role, so the existing RBAC limits it to a subset of endpoints/actions (owner-only to create; reuses the merchant staff model + seat billing). See the JS / Python SDK READMEs.

UCP (Universal Commerce Protocol)

agents.u.cash implements the UCP discovery layer:

• /.well-known/ucp - business profile (capabilities, payment handlers, EC P-256 signing key).
• /catalog.json - schema.org/Product JSON-LD catalog (the merchant's Shop products).
• /catalog/search | /catalog/lookup | /catalog/product - structured catalog REST.
• /checkout-sessions - UCP checkout sessions (create → complete → payment handlers).
• /orders/{id} - order status.

UCP is an open standard (ucp.dev, Apache-licensed; co-developed by Google/Shopify/Amazon/Walmart/Microsoft/Meta/Stripe/Visa/Mastercard).

Protocol

402.onl - the 402 Online Protocol.

License

MIT