API reference

AceChange Agent API — documentation

The precise reference: base URL, auth, every endpoint, MCP tools, events and errors. Non-custodial throughout.

Live: /health · machine-readable /agent · guide: connect · open-source SDK on GitHub.

Base & authentication

Base URL: https://www.acechange.io/wp-json/acechange-agent/v1

  • Headers: X-Ace-Agent-Key, X-Ace-Agent-Timestamp (unix seconds, ±300s), X-Ace-Agent-Sign.
  • Signature = HMAC-SHA256( METHOD + "\n" + ROUTE + "\n" + TS + "\n" + BODY , key ) where key = hex(sha256(secret)).
  • ROUTE = the namespaced route, e.g. /acechange-agent/v1/pay (the /wp-json-prefixed form is also accepted). BODY = raw body; "" for GET.
  • est_usd (> 0) is REQUIRED on swap/pay/cross-chain so spend caps apply.
  • The open-source SDKs (Python/TypeScript) sign for you.

Endpoints

Discovery & limitsMicro-swap (Base, 0x gasless)Cross-chain (real BTC / USDT / XMR)Pay anyoneCommerceBilling & usagePay-per-callEvents & webhooksWallet registryFunding & visibility

Discovery & limits

GET/agent

Public capability card: auth spec, all endpoints, MCP tools, error codes.

GET/health

Public status: enabled, micro_configured, cross_chain_configured.

GET/currencies

Supported Base micro tokens.

GET/limits

This key's caps: max_tx_usd, daily_usd_cap, per_min.

Micro-swap (Base, 0x gasless)

POST/swap/quote

{sell,buy,amount,taker} → price + the EIP-712 trade to sign.

POST/swap/submit

{signed,est_usd} → relays the signed trade to the 0x relayer.

GET/swap/status

?trade_hash= → trade status.

Cross-chain (real BTC / USDT / XMR)

GET/ff/currencies

Valid cross-chain currency codes.

POST/ff/estimate

{from,to,amount,type?,direction?} → rate + amounts.

POST/ff/create

{from,to,amount,toAddress,type?,tag?,est_usd,idempotency_key?} → deposit + receive block.

GET/ff/status

?order= → mapped status (scoped to your key).

POST/ff/emergency

{order_id,choice(EXCHANGE|REFUND),address?} → act on a stuck swap.

Pay anyone

POST/pay

{to,token,amount,from?,est_usd} → unsigned tx to sign; your spend caps applied.

Commerce

POST/commerce/merchant

{receive_address,label?,webhook_url?,fee_bps?} → merchant_id + webhook_secret (once).

POST/commerce/product

{name,price_usd,description?,currency?}.

GET/commerce/products

List your products.

POST/commerce/checkout

{product_id|amount,expires_in?} → pay_to (merchant), EIP-681, x402, checkout_url.

POST/commerce/confirm

{order_id,x_payment|tx_hash} → verify + mark paid + webhook.

GET/commerce/order

?order= → public status (buyer poll).

GET/commerce/watch

?order= → public, on-chain auto-confirm (IP-rate-limited).

POST/commerce/refund

{order_id,to_address} → reverse transfer the merchant signs.

POST/commerce/deliver

{order_id} → mark delivered.

Billing & usage

POST/billing/subscription

{amount_usd,period(day|week|month),label?}.

GET/billing/subscriptions

List subscriptions.

POST/billing/cancel

{subscription_id}.

POST/billing/usage

{meter,units,unit_price_usd}.

POST/billing/invoice

{meter} → one checkout for the metered total.

Pay-per-call

GET/x402/premium

402 + USDC requirements; pay with X-PAYMENT, get the resource.

GET/l402/premium

402 + Lightning invoice; pay, retry with Authorization: L402 <token>:<preimage>.

GET/x402/info | /l402/info

Rail status.

Events & webhooks

GET/events

Your recent events.

POST/webhooks/register

{url} (public HTTPS) → secret; events POSTed with X-Ace-Event-Signature.

GET/webhooks

List webhooks.

POST/webhooks/delete

{url}.

Wallet registry

GET/wallet/provision

SDK config (no key material).

POST/wallet/register

{owner_address,label?}.

POST/wallet/smart-account

{smart_account,owner_address,label?} (ERC-4337).

POST/wallet/session

{session_address,per_tx_usd,daily_usd,allowed_tokens,allowed_recipients,expires_in?}.

GET/wallet/policy

?session= → policy.

POST/wallet/revoke

{session_address} → kill switch.

Funding & visibility

GET/fund/link

?wallet=&amount=&crypto=&network= → fiat on-ramp link to the agent wallet.

GET/activity

Your activity history + totals.

GET/activity/view

?key=&token= → read-only human dashboard feed.

MCP tools

POST /mcp (JSON-RPC 2.0): initialize (negotiates protocolVersion, latest 2025-06-18), tools/list (public), tools/call (agent-auth; business errors return result.isError=true).

ace_currencies ace_limits ace_activity ace_events ace_fund ace_swap_quote ace_swap_submit ace_swap_status ace_pay ace_ff_currencies ace_ff_estimate ace_ff_create ace_ff_status ace_register_merchant ace_create_product ace_create_checkout ace_order_status ace_create_subscription ace_record_usage ace_invoice

Events

Subscribe via POST /webhooks/register (signed X-Ace-Event-Signature) or pull GET /events:

swap.submitted swap.created swap.completed swap.refunded swap.expired payment.built order.paid order.refunded order.delivered subscription.due invoice.created

Error codes

Shape: { code, message, data:{status} } — branch on code.

codeHTTPmeaning
agent_disabled503module off
agent_auth401bad/missing key, timestamp or signature
rate_limited429velocity / IP limit — back off
est_usd_required400pass est_usd > 0
tx_too_large403over per-tx cap
daily_cap403over daily USD cap (UTC day)
*_not_configured503rail not set up by the operator
ff_upstream / upstream502cross-chain provider error (message carries a provider code)
forbidden403order/resource belongs to another key
no_order404unknown order

Non-custodial: AceChange builds / verifies / notifies — never holds, routes or freezes funds. Get an agent key from the operator to go live, or read the open-source SDK on GitHub.

Marcus Richardson — Founder & Privacy Research Lead · www.linkedin.com · Last updated June 19, 2026