API reference
Every endpoint of the agents.u.cash API, generated from the same source as the OpenAPI 3.1 spec (v0.6.13). Plain-text twin: llms.txt. New here? Start with the 60-second quickstart.
Account (36)
Signup, activation, wallets, webhook, settlement log
POST
/v1/signup
PUBLIC
Register an agent account (returns the api_key immediately; usable at $0; email verification is optional and grants $5 free credit (up to $2,500 in transactions))
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
email | string | required | |
password | string | required | |
primary_wallet | string | optional | |
agreed_to_terms | boolean | optional | Send true to agree to the Terms of Service (https://u.cash/legal/terms). An explicit false is rejected; omitted is treated as agreed for backward compatibility. |
| Responses | |||
| 200 | {api_key, activated, next} | ||
| 400 | validation error | ||
POST
/v1/top-up
API KEY
Create a credit top-up checkout (>= $1; adds platform credit; email verification is the activation gate; allowed pre-activation)
Parameters, body & responses
| Body | |||
|---|---|---|---|
amount | number | optional | |
| Responses | |||
| 200 | {url, amount, activated, next} | ||
GET
/v1/agent
API KEY
Account snapshot: activation, balance, wallets, webhook URL, earnings summary
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {email, activated, primary_wallet, credit_balance, webhook_url, wallets, settlements_count, total_earned} | ||
POST
/v1/agent
API KEY
Set the settlement webhook URL {webhook_url}
Parameters, body & responses
| Body | |||
|---|---|---|---|
webhook_url | string | optional | |
| Responses | |||
| 200 | {webhook_url} | ||
GET
/v1/me
API KEY
Alias of /v1/agent (account snapshot).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | same as /v1/agent | ||
GET
/v1/account
API KEY
Alias of /v1/agent (account snapshot).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | same as /v1/agent | ||
GET
/v1/webhooks
API KEY
Webhook discoverability alias (canonical surface is /v1/webhook).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {webhook_url, how_to_set, rotate_secret} | ||
GET
/v1/webhook
API KEY
Read the settlement webhook (masked): {url, has_secret, secret_last4}.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {url, has_secret, secret_last4} | ||
POST
/v1/webhook
API KEY
Set the webhook URL (auto-generates the HMAC secret on first set, shown once), rotate the secret ({rotate_secret:true}), or clear ({url:''}). Writes need the settings.edit capability for a subagent key.
Parameters, body & responses
| Body | |||
|---|---|---|---|
url | string | optional | |
rotate_secret | boolean | optional | |
| Responses | |||
| 200 | {url, secret} | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
DELETE
/v1/webhook
API KEY
Clear the webhook URL. settings.edit capability for a subagent key.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {url:'', cleared:true} | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
GET
/v1/wallets
API KEY
Your receive addresses {wallets{asset:address}}.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {wallets:{asset:address}} | ||
POST
/v1/wallets
API KEY
Set the agent's own receive address for an asset (where buyer funds land; accepts comma-separated for the Address List).
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
asset | string | required | cryptocurrency code, e.g. btc, eth, sol, trx, usdt, usdc, ucash, usdc_base (the x402 gasless rail); or a custom-token code you added via /v1/custom-tokens |
address | string | required | |
| Responses | |||
| 200 | {asset, address} | ||
| 400 | uxc_unknown_asset | uxc_bad_address | ||
PUT
/v1/wallets
API KEY
Toggle a coin on/off (?asset=<code>, body {active:true|false}) without losing its address. GET ?all=1 lists paused coins.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {asset, active} | ||
| 400 | uxc_unknown_asset | uxc_invalid_request | ||
DELETE
/v1/wallets
API KEY
Remove a coin receive address (?asset=<code>); the coin stops being accepted until set again.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {asset, deleted:true} | ||
| 400 | uxc_unknown_asset | uxc_invalid_request | ||
GET
/v1/stripe
API KEY
Masked Stripe config + the webhook endpoint to register
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {configured, active, mode, secret_key(masked), product_id, webhook_secret(masked), publishable_key, webhook_endpoint, webhook_events} | ||
POST
/v1/stripe
API KEY
Connect the agent's OWN Stripe account (card rail); verifies the key + product against Stripe, then stores. payments.processors.edit capability for a subagent key.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
Your own Stripe account keys - enables the card (redirect) rail. Verified against Stripe before storing; secrets are never returned in full. | |||
secret_key | string | required | sk_live_... or sk_test_... |
product_id | string | required | a one-time product id (prod_...) |
webhook_secret | string | required | whsec_... from registering the webhook endpoint |
publishable_key | string | optional | optional pk_live_... or pk_test_... |
| Responses | |||
| 200 | masked config + webhook_endpoint | ||
| 400 | uxc_invalid_request | uxc_stripe_invalid | ||
| 403 | uxc_forbidden (subagent key without payments.processors.edit) | ||
DELETE
/v1/stripe
API KEY
Disconnect Stripe (disables card payments). payments.processors.edit capability for a subagent key.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {configured:false, cleared:true} | ||
| 403 | uxc_forbidden (subagent key without payments.processors.edit) | ||
GET
/v1/custom-tokens
API KEY
List the agent custom tokens
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {custom_tokens:[{code,type,network,name,contract_address,decimals}]} | ||
POST
/v1/custom-tokens
API KEY
Add a custom token (ERC-20/TRC-20/SPL); then POST /v1/wallets to set its receive address. Auto-detected on-chain like any coin. settings.edit capability for a subagent key.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
type | string · erc-20 | bep-20 | base-20 | polygon-20 | arb-20 | op-20 | avax-20 | trc-20 | spl | required | |
code | string | required | |
contract_address | string | required | |
decimals | integer | required | |
name | string | required | |
rate | string | optional | |
rate_url | string | optional | |
confirmations | integer | optional | |
img | string | optional | |
| Responses | |||
| 200 | the stored token | ||
| 400 | uxc_invalid_request | uxc_custom_token_exists | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
DELETE
/v1/custom-tokens
API KEY
Remove a custom token by code. settings.edit capability for a subagent key.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
code | string · query | required | |
| Responses | |||
| 200 | {deleted, custom_tokens} | ||
| 404 | uxc_not_found | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
GET
/v1/settings
API KEY
The agent safe settings: confirmations policy (default + per-coin + value-increase), webhook url (+ masked secret), currency, address_reuse_cooldown, payment preferences, notification email, branding
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {confirmations:{default,coins,increase}, webhook:{url,has_secret,secret_last4}, currency, address_reuse_cooldown, payment:{accept_underpayments,redirect}, notifications:{email}, branding:{brand_name,logo_url,logo_url_dark,color_1,color_2,color_3}} | ||
PUT
/v1/settings
API KEY
Partially update the agent safe settings (any subset). webhook.rotate_secret=true mints a new signing secret. No custodial/node/private-key/payout fields.
Parameters, body & responses
| Body | |||
|---|---|---|---|
confirmations | object | optional | |
webhook | object | optional | |
currency | string | optional | |
payment | object | optional | |
notifications | object | optional | |
branding | object | optional | |
web3_names | object | optional | |
| Responses | |||
| 200 | the full updated shape | ||
GET
/v1/settlements
API KEY
The agent's earnings log (settled + underpaid resource payments)
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {settlements:[...]} | ||
GET
/v1/integrations
API KEY
Read third-party integration credentials you have stored (Discord, Telegram, BigCommerce, Ecwid, Wix). Returned in plaintext to the authenticated agent. settings.edit capability for a subagent key (reads expose secrets).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {integrations:{discord?,telegram?,bigcommerce?,ecwid?,wix?}} | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
PUT
/v1/integrations
API KEY
Write third-party integration credentials. settings.edit capability for a subagent key.
Parameters, body & responses
| Body | |||
|---|---|---|---|
integrations | object | optional | |
| Responses | |||
| 200 | {integrations:{...}} | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
POST
/v1/account-email
API KEY
OWNER KEY ONLY (an sa_ subagent key gets 403 uxc_forbidden). Add/change the account email (sends verification; login anchor + encryption key stay stable so wallets keep decrypting). Verifying grants $5 free credit (up to $2,500 in transactions).
Parameters, body & responses
| Body | |||
|---|---|---|---|
email | string | optional | |
| Responses | |||
| 200 | {email, verification_required, next} | ||
| 403 | uxc_forbidden when authenticated with a subagent key | ||
POST
/v1/reset-password
API KEY
OWNER KEY ONLY (an sa_ subagent key gets 403 uxc_forbidden). Reset the overseer web-login password (no-email agents have no email-reset path)
Parameters, body & responses
| Body | |||
|---|---|---|---|
new_password | string | optional | |
| Responses | |||
| 200 | {reset:true} | ||
| 403 | uxc_forbidden when authenticated with a subagent key | ||
POST
/v1/resend-verification
API KEY
Resend the email verification link (3-day expiry for agents; no-op if already verified)
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {sent, next} | ||
POST
/v1/exact-relay
API KEY
Manage the exact relayer for instant, gasless USDC-on-Base settlement (ON by default, opt-out; seller billed gas + 21% per gasless settle). Writes (POST/DELETE) need the settings.edit capability for a subagent key.
Parameters, body & responses
| Body | |||
|---|---|---|---|
enabled | integer | optional | 1 = gasless (default), 0 = opt out (buyer-pays-gas) |
private_key | string | optional | ignored (relayer is platform-managed) |
| Responses | |||
| 200 | masked relay config | ||
| 403 | uxc_forbidden (subagent key without settings.edit) | ||
GET
/v1/account-info
API KEY
Alias of /v1/agent (account snapshot).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | same as /v1/agent | ||
GET
/v1/transactions
API KEY
Full transaction history with filters (type, status, asset, store_id, date range, search), pagination, ?transaction_id=N for one transaction, ?transaction_id=N&webhook_log=1 for its webhook deliveries, and ?download=1 (+any filters) for the CSV export.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {transactions:[...], pagination:{total,limit,offset}} | {transaction:{...}} | {webhook_log:[...]} | CSV bytes | ||
POST
/v1/transactions
API KEY
Per-transaction actions: ?transaction_id=N&action=refund (needs a refund-capable connected node/Stripe), action=resend-webhook (needs a webhook URL), action=submit-hash {hash} (attach the on-chain hash you paid with). Subagent store_scope is enforced.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
transaction_id | integer · query | required | |
action | string · query | required | |
| Body | |||
hash | string | optional | |
| Responses | |||
| 200 | {refunded:true} | {resent:true, webhook_response} | {submitted:true, tx_hash} | ||
| 400 | state guard errors (e.g. refunds-not-enabled, no webhook configured) | ||
GET
/v1/payout-info
API KEY
List payout-info requests (type-4: merchant-mediated fiat<->crypto/OTC payouts).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {requests:[...]} | ||
POST
/v1/payout-info
API KEY
Request payout info -> {transaction_id, link}. ?transaction_id=N&action=complete marks it completed.
Parameters, body & responses
| Body | |||
|---|---|---|---|
payout_asset | string | optional | |
details | string | optional | |
| Responses | |||
| 200 | {transaction_id, link} | {completed:true, id} | ||
GET
/v1/billing
API KEY
Balances + lander slot pack status: {credit_balance, ucash_points, lander_slots}.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {credit_balance, ucash_points, lander_slots:{...}} | ||
POST
/v1/billing
API KEY
Actions: {action:"buy-lander-pack", qty} (debits credit) or {action:"redeem-ucash", amount} (converts UCASH points to platform credit).
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
action | string · buy-lander-pack | redeem-ucash | required | |
qty | integer | optional | |
amount | number | optional | |
| Responses | |||
| 200 | the updated balances | ||
| 402 | uxc_insufficient_balance | ||
Storefront (23)
Read/edit the agent's own storefront (Shop Page): chrome, free-canvas layout, custom templates, image assets
GET
/v1/site
API KEY
Read the agent's storefront (Shop Page): shop-* chrome values, free-canvas layout, themes/layouts, style vars. ?resource=templates lists custom templates; ?resource=templates&id=N fetches one.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
resource | string · query | optional | |
id | integer · query | optional | |
| Responses | |||
| 200 | {site:{values, template, themes, layouts, layout, style_vars}} | {templates:[...]} | {template:{...}} | ||
PUT
/v1/site
API KEY
Update the storefront chrome (shop-* only, merged) and/or the free-canvas layout: {chrome?, layout?}. Or update a custom template: ?resource=templates&id=N {chrome, css?, layout?}. Non-GET ops need the design.edit capability for a subagent key.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
resource | string · query | optional | |
id | integer · query | optional | |
| Body | |||
chrome | object | optional | |
layout | object | optional | |
| Responses | |||
| 200 | {saved:true} | ||
| 403 | uxc_forbidden (subagent key without design.edit) | ||
POST
/v1/site
API KEY
Create a custom template (?resource=templates {name, base_template?, base_theme?, chrome, css?, layout?}), apply one (?resource=templates&action=apply&id=N), or upload an image (?resource=assets, multipart file). design.edit capability for a subagent key.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
resource | string · query | optional | |
action | string · query | optional | |
id | integer · query | optional | |
| Responses | |||
| 200 | {id, saved:true} | {applied:true} | {url} | ||
| 403 | uxc_forbidden (subagent key without design.edit) | ||
DELETE
/v1/site
API KEY
Delete a custom template: ?resource=templates&id=N. design.edit capability for a subagent key.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
resource | string · query | optional | |
id | integer · query | optional | |
| Responses | |||
| 200 | {deleted:true} | ||
| 403 | uxc_forbidden (subagent key without design.edit) | ||
GET
/v1/checkouts
API KEY
List shop products (the checkout items a buyer sees), or fetch one (?checkout_id=N / slug).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {checkouts:[...]} | {checkout:{...}} | ||
POST
/v1/checkouts
API KEY
Create a shop product: title, price, asset, description, etc. The buyer-facing checkout is born immediately. Optional Idempotency-Key header makes retried creates replay instead of duplicating.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
Idempotency-Key | string · header | optional | retry-safe create: the same key + body replays the original response (Idempotency-Replayed: true) instead of duplicating |
| Body (required) | |||
title | string | required | |
price | number | required | |
currency | string | optional | |
asset | string | optional | |
description | string | optional | |
| Responses | |||
| 200 | {checkout:{...}} | ||
PUT
/v1/checkouts
API KEY
Update a product (?checkout_id=N). Optimistic concurrency: send the version you read; a stale version is rejected.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
checkout_id | integer · query | required | |
| Responses | |||
| 200 | {checkout:{...}} | ||
| 409 | version mismatch | ||
DELETE
/v1/checkouts
API KEY
Delete a product (?checkout_id=N).
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
checkout_id | integer · query | required | |
| Responses | |||
| 200 | {deleted:true, id} | ||
GET
/v1/stores
API KEY
List stores (multi-store). Subagents may list even without manage rights.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {stores:[...]} | ||
POST
/v1/stores
API KEY
Create a store {label, webhook_url} -> returns its api_key + cloud_token + webhook_secret ONCE (write them down; keys are hash-at-rest and never shown again - the list exposes only the masked api_key_hint). POST ?store_id=N&rotate=api_key|webhook_secret|cloud_token rotates a credential (rotate=api_key returns the fresh raw key once); POST ?store_id=N&action=test-webhook fires a test delivery.
Parameters, body & responses
| Body | |||
|---|---|---|---|
label | string | optional | |
webhook_url | string | optional | |
| Responses | |||
| 200 | {store:{...}} | {api_key, cloud_token, webhook_secret} | {test:{...}} | ||
PUT
/v1/stores
API KEY
Update a store (?store_id=N) label/webhook_url/status.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
store_id | integer · query | required | |
| Responses | |||
| 200 | {store:{...}} | ||
DELETE
/v1/stores
API KEY
Delete a store (?store_id=N). Owner-only.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
store_id | integer · query | required | |
| Responses | |||
| 200 | {deleted:true, id} | ||
GET
/v1/landers
API KEY
List landing pages, fetch one (?lander_id=N), or its inbound offers (?lander_id=N&offers=1).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {landers:[...]} | {lander:{...}} | {offers:[...]} | ||
POST
/v1/landers
API KEY
Turn an is_lander=1 checkout into a landing page {checkout_id, tpl?: spotlight}. Free-tier slot accounting applies (see /v1/billing); a pack adds slots.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
checkout_id | integer | required | a checkout created with is_lander=1 (POST /v1/checkouts) |
tpl | string | optional | |
| Responses | |||
| 200 | {lander_id} | ||
| 402 | no-free-lander-slots (buy a pack via /v1/billing) | ||
| 404 | checkout is not a lander | ||
PUT
/v1/landers
API KEY
Update a lander (?lander_id=N), or set an offer status (?lander_id=N&offer_id=M&offer_status=new|viewed|accepted|rejected|spam).
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
lander_id | integer · query | required | |
| Responses | |||
| 200 | {updated:true, id} | {updated:true, offer_id} | ||
DELETE
/v1/landers
API KEY
Delete a lander (?lander_id=N); frees its slot.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
lander_id | integer · query | required | |
| Responses | |||
| 200 | {deleted:true, id} | ||
GET
/v1/discount-codes
API KEY
List discount codes (multiplier codes, e.g. 0.8 = 20% off).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {discount_codes:[...]} | ||
POST
/v1/discount-codes
API KEY
Add a code {code, multiplier, ...}.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
code | string | required | |
multiplier | number | required | |
| Responses | |||
| 200 | {discount_codes:[...], added:{code}} | ||
PUT
/v1/discount-codes
API KEY
Bulk-replace codes with an array body (import/export workflow).
Parameters, body & responses
| Body | |||
|---|---|---|---|
codes | array | optional | |
| Responses | |||
| 200 | {discount_codes:[...], replaced:N} | ||
DELETE
/v1/discount-codes
API KEY
Remove a code (?code=<code>).
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
code | string · query | required | |
| Responses | |||
| 200 | {removed, discount_codes} | ||
GET
/v1/custom-fields
API KEY
List checkout custom form fields (text/checkbox/textarea/select).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {custom_fields:[...]} | ||
POST
/v1/custom-fields
API KEY
Add a custom field {type, label, options?, required?}.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
type | string · text | checkbox | textarea | select | required | |
label | string | required | |
options | array<string> | optional | |
required | boolean | optional | |
| Responses | |||
| 200 | {custom_fields:[...], added:true} | ||
DELETE
/v1/custom-fields
API KEY
Remove a field (?index=N).
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
index | integer · query | required | |
| Responses | |||
| 200 | {custom_fields:[...], removed_index} | ||
Sell (402) (7)
Create resources + build the multi-coin accepts[]
POST
/v1/resources
API KEY
Create a priced resource (optional max_per_caller to cap a payer's spend in a window). Optional Idempotency-Key header makes retried creates replay instead of duplicating.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
Idempotency-Key | string · header | optional | retry-safe create: the same key + body replays the original response (Idempotency-Replayed: true) instead of duplicating |
| Body | |||
amount | number | required | fiat price, e.g. 0.05 |
currency | string | optional | |
accepted_assets | array<string> | optional | defaults to all configured wallets |
webhook_url | string | optional | notified (HMAC-signed) on settlement |
max_per_caller | object | optional | optional per-caller spend cap; a payer whose settled spend in the window reaches amount is refused new authorization |
checkout_url | string | optional | response field: the canonical buyer door on pay.u.cash (/checkout/<enc>?cloud=<token>). A human gets the HTML checkout; an agent fetches ?agent=1 for the 402 manifest; an x402 client sends X-PAYMENT |
test | boolean | optional | test mode: settles instantly for $0, no wallet needed, marked in responses, excluded from earnings |
| Responses | |||
| 200 | {res_id, amount, currency, accepted_assets, max_per_caller, checkout_url} | ||
PUT
/v1/resources
API KEY
Set (or clear) a resource's per-caller spend cap. ?res_id=N { max_per_caller: {amount, window_hours} | null }
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
res_id | string · query | required | |
| Body | |||
max_per_caller | max_per_caller | optional | |
| Responses | |||
| 200 | {res_id, max_per_caller} | ||
GET
/v1/resources
API KEY
List resources, fetch one (?res_id=, incl. max_per_caller), or its per-caller spend ledger (?res_id=N&callers=1)
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {resources:[...]} | one resource | {callers:[{caller,spend,payments}]} | ||
DELETE
/v1/resources
API KEY
SOFT disable a resource: removes it from the list and the /r/ door but keeps its settled history in GET /v1/settlements. ?res_id=N
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
res_id | string · query | required | |
| Responses | |||
| 200 | {disabled:true, res_id} | ||
POST
/v1/payment-requests
API KEY
Create a ONE-OFF payment request (a pay.u.cash /id/<enc> link that closes when paid or after the expiry). Distinct from resources (persistent).
Parameters, body & responses
| Body | |||
|---|---|---|---|
amount | number | optional | |
currency | string | optional | |
asset | string | optional | |
asset_amount | number | optional | |
cryptocurrency | string | optional | |
title | string | optional | |
note | string | optional | |
expiry | string · 15m | 1h | 24h | 7d | 30d | never | optional | |
redirect | string | optional | |
external_reference | string | optional | |
| Responses | |||
| 200 | {transaction_id, encrypted_id, url, amount, currency, cryptocurrency, expiry, status} | ||
GET
/v1/payment-requests
API KEY
List your one-off payment requests, or fetch one (?id=<id>).
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {payment_requests:[...]} | one request | ||
POST
/v1/challenge
API KEY
Build the multi-coin 402 accepts[] for a resource {res_id}
Parameters, body & responses
| Body | |||
|---|---|---|---|
res_id | string | required | |
| Responses | |||
| 200 | {res_id, amount, currency, accepts:[...]} | ||
Buy (5)
Fetch the 402 door, pay, and settle a payment (public)
POST
/v1/verify
PUBLIC
Optional instant settle (POST the on-chain tx hash). Buyer-push: callable with just the challengeId (no key) after paying, OR with the seller X-Api-Key. The platform also auto-detects the on-chain payment.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
challengeId | string | required | from an accepts[] entry |
hash | string | required | on-chain transaction hash |
| Responses | |||
| 200 | {settled:true} | {status:pending, confirmations, required} | {status:underpaid} | ||
| 404 | challenge not found | ||
| 410 | challenge expired | ||
GET
/r/{id}
PUBLIC
The 402 door (back-compat alias of pay.u.cash /checkout/<enc>; same engine, same challenges - prefer the resource checkout_url). HTTP 402 + accepts[] (machine; + WWW-Authenticate: x402 + paymentRequirements[] when an exact entry is offered), a payable HTML page (browser), or 200 if settled. With an X-PAYMENT header it verifies + settles an exact (x402) payment and returns X-PAYMENT-RESPONSE. Public.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
id | string · path | required | |
| Responses | |||
| 402 | accepts[] + paymentRequirements[] | ||
| 200 | settled or the HTML page | ||
| 202 | exact payment verified, pending on-chain settlement | ||
POST
/v1/exact-verify
PUBLIC
x402 facilitator verify: is this signed EIP-3009 USDC-on-Base payment acceptable? Pure signature check, no settle.
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
x402Version | integer | optional | |
paymentPayload | object | optional | |
paymentRequirements | object | optional | carries resource (the /r/{res_id} URL) |
| Responses | |||
| 200 | {isValid, invalidReason?, payer} | ||
POST
/v1/exact-settle
PUBLIC
x402 facilitator settle: verify the signed payment AND settle (relay by default; opt-out, or POST a tx hash, for verify-only).
Parameters, body & responses
| Body (required) | |||
|---|---|---|---|
x402Version | integer | optional | |
paymentPayload | object | optional | |
paymentRequirements | object | optional | |
| Responses | |||
| 200 | {success, transaction, network, payer, errorReason?}. Hard failures (bad signature, expiry, payee mismatch, no open challenge) ALSO return this shape with success:false + errorReason. | ||
GET
/relayer/{id}
PUBLIC
Public: is this resource sponsored by a gasless relayer? Returns the relayer address + its Base ETH balance (buyers pay zero gas when funded). Also the human-facing /fund-relayer page target.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
id | string · path | required | |
| Responses | |||
| 200 | {res_id, configured, active, funding, funded_address, balance, network, pay_to} | ||
| 404 | resource not found | ||
UCP (8)
Universal Commerce Protocol: discovery + multi-item checkout sessions + AP2 mandates (public; merchant resolved from host or ?cloud=)
POST
/checkout-sessions
PUBLIC
Create a UCP checkout session (multi-item, mixed-currency cart). Merchant resolved from the host or ?cloud=.
Parameters, body & responses
| Body | |||
|---|---|---|---|
UCP buyer checkout (multi-item, mixed-currency). The merchant is resolved from the host or ?cloud=, NOT X-Api-Key. | |||
line_items | array<object> | required | one entry per item |
currency | string | optional | cart currency for mixed-currency carts (default: the shared item currency, else the merchant default) |
buyer | object | optional | |
context | object | optional | |
| Responses | |||
| 200 | {id, status, currency, line_items, totals, ap2:{merchant_authorization, nonce}} | ||
GET
/checkout-sessions/{id}
PUBLIC
Fetch a checkout session (status: incomplete -> ready_for_complete -> completed)
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
id | string · path | required | |
cloud | string · query | optional | |
| Responses | |||
| 200 | the session | ||
| 404 | not found | ||
POST
/checkout-sessions/{id}/complete
PUBLIC
Mint payment challenges -> ready_for_complete. Optional AP2: {ap2:{checkout_mandate}} holder-proof (verified, else 401).
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
id | string · path | required | |
| Body | |||
AP2 mandate (dev.ucp.shopping.ap2_mandate) - optional holder-proof buyer authorization on complete. | |||
checkout_mandate | string | optional | buyer-signed SD-JWT-VC binding the payment to this checkout |
| Responses | |||
| 200 | ready_for_complete + payment_handlers[] | ||
| 401 | mandate_invalid_signature | mandate_expired | mandate_scope_mismatch | ||
POST
/checkout-sessions/{id}/cancel
PUBLIC
Cancel a checkout session
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
id | string · path | required | |
| Responses | |||
| 200 | canceled | ||
GET
/orders/{id}
PUBLIC
A checkout session viewed as a UCP order (per-item fulfillment status)
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
id | string · path | required | |
| Responses | |||
| 200 | {id, checkout_id, currency, line_items, fulfillment, totals} | ||
| 404 | not found | ||
POST
/catalog/search
PUBLIC
Search the merchant catalog (text + price filter + pagination)
Parameters, body & responses
| Body | |||
|---|---|---|---|
query | string | optional | |
filters | object | optional | |
pagination | object | optional | |
| Responses | |||
| 200 | {products[], pagination} | ||
POST
/catalog/lookup
PUBLIC
Batch catalog lookup by id
Parameters, body & responses
| Body | |||
|---|---|---|---|
ids | array<string> | optional | |
| Responses | |||
| 200 | {products[]} | ||
POST
/catalog/product
PUBLIC
Fetch a single product by id
Parameters, body & responses
| Body | |||
|---|---|---|---|
id | string | optional | |
| Responses | |||
| 200 | one product | ||
| 404 | uxc_not_found | ||
Subagents (4)
Owner-only: delegate scoped sa_ API keys with a limited RBAC role (create/list/update/rotate/delete)
GET
/v1/subagents
API KEY
List the agent subagents (scoped sa_ API keys; never returns the api_key). Owner-only.
Parameters, body & responses
| Responses | |||
|---|---|---|---|
| 200 | {subagents:[{id,role,role_name,permissions,store_scope,status,display_name,created_at}], balance, prices, slots_free} | ||
POST
/v1/subagents
API KEY
Create a subagent with a limited role (or custom permissions). The sa_ api_key is returned ONCE; a subagent with no free slot debits credit_balance. Owner-only. (POST ?subagent_id=N&rotate=key rotates the key.)
Parameters, body & responses
| Body | |||
|---|---|---|---|
role | string | required | clerk|teller|lead|supervisor|manager|director|officer|admin|master-admin|accountant|auditor|designer|custom |
permissions | array<string> | optional | custom-role capability slugs (e.g. transactions.view, checkouts.edit, payment-links.create) |
role_name | string | optional | |
display_name | string | optional | |
store_scope | array<integer> | optional | restrict to these store ids (empty = all) |
| Responses | |||
| 200 | {api_key, subagent, seat_fee, slot, new_balance} | ||
| 402 | uxc_insufficient_balance | ||
PUT
/v1/subagents
API KEY
Update a subagent role/permissions/store_scope/status/display_name. ?subagent_id=N. Owner-only.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
subagent_id | integer · query | required | |
| Body | |||
role | string | optional | |
permissions | array<string> | optional | |
role_name | string | optional | |
display_name | string | optional | |
store_scope | array<integer> | optional | |
status | string · active | suspended | optional | |
| Responses | |||
| 200 | {subagent, seat_fee} | ||
DELETE
/v1/subagents
API KEY
Delete a subagent (its key stops authenticating; the seat slot frees). ?subagent_id=N. Owner-only.
Parameters, body & responses
| Parameters | |||
|---|---|---|---|
subagent_id | integer · query | required | |
| Responses | |||
| 200 | {deleted, id} | ||