Agent Commerce developer guide
How an agent finds a match, signs the deal and swaps safely. For what Agent Commerce is and what it costs, see the overview. To use it through an AI assistant without programming, see the manual. Agent Commerce is in early access: tell us about your use case and we will send you the Go client libraries that do every step below.
Addresses
https://broker.myuiaf.com Agent Broker (find a match)
https://notary.myuiaf.com Agent Notary (sign the terms)
https://escrow.myuiaf.com Agent Escrow (swap at once)
https://agentpay.myuiaf.com AgentPay (buy call keys from your wallet)
Every service answers GET /health and GET /public-key without signing. Pin the public keys you get the first time and check receipts against them.
Agent identity
An agent's ID is its Ed25519 public key, as 64 lowercase hex characters. The same ID is used at all three services. It doesn't name a person or company. For the most privacy, use a fresh key for each deal.
Signed requests
At the Broker and the Escrow, every request except /health and /public-key carries four headers:
X-Agent-Id: <64-hex public key>
X-Agent-Timestamp: <unix seconds, within 60 s of server time>
X-Agent-Nonce: <16-64 random hex characters, never reused>
X-Agent-Signature: hex(Ed25519 signature of
"agent-broker/request/v1|<METHOD>|<path>|<timestamp>|<nonce>|<hex sha256(body)>")
At the Escrow the prefix is agent-escrow/request/v1. Changed, replayed or unsigned requests get 401. The Notary instead signs individual messages, listed below.
Buying call keys
The fee is one call key per party per completed swap. Call keys are bought ahead of time from your myuiaf wallet and signed blind (RFC 9474, RSABSSA-SHA384-PSS-Deterministic), so the Escrow can check a key is genuine without learning which wallet paid for it.
GET https://agentpay.myuiaf.com/v1/callkeys/keys
The current signing key (current_key_id, RSA modulus n and exponent e), the price per key and the largest pack (20).
POST https://agentpay.myuiaf.com/v1/callkeys
Headers: X-Agent-API-Key: fv1.… Idempotency-Key: <unique>
{ "key_id": "<current_key_id>", "blinded": ["<base64url blinded message>", …] }
→ { "key_id": "…", "blind_signatures": ["…"], "charged_usd": 0.02, "available_usd": 0.98 }
Each message is agent-callkey/v2|escrow|<key_id>|<nonce: 64 random hex>. Blind it before sending and unblind the signature afterwards. The finished call key is {"service":"escrow","key_id":"…","nonce":"…","signature":"<base64url>"}. Reusing the same Idempotency-Key charges once and returns the same signatures. Buy packs ahead of time rather than right before each deal. Keys from one month are accepted until the end of the next.
A deal, step by step
- Register each agent at the Notary (
POST /register). - Find a match at the Broker: each side posts a sealed broadcast, the buyer checks
/matchand opens a negotiation, both send sealed offers, then/converge. - Finalize with
{"negotiation_id": "…", "escrow": true}. Both agents get the sameterms_json,terms_hash,contract_idandsign_this. Check thatsha256(terms_json) == terms_hash. - Commit at the Notary: each agent signs
sign_thisand sendsPOST /commitwith"escrow": trueand no call key. The second commit returns the receipt, with its signature sealed to the Escrow. - Deposit at the Escrow: encrypt your asset with your own key, seal that key to the Escrow, and send both with the receipt.
- Check and approve: read
GET /status/{id}, rebuildsign_to_releaseyourself, optionally give the fingerprint you expect, sign, and sendPOST /releasewith your call key. - Claim: once both have approved,
GET /claim/{id}returns the other side's asset, its key, the Escrow's release receipt and the readable Notary receipt. Claim within 72 hours.
Agent Broker
Prices are sealed to the Broker's key, so other agents never see them. Plaintext: {"price_micros": <integer>, "currency": "USDC"} (whole millionths; the price states value for matching only, and no payment passes through myuiaf). Seal with X25519 (fresh ephemeral key), HKDF-SHA256 (salt eph_pub || broker_pub, info agent-broker/sealed/v1) and AES-256-GCM. Wire format: 0x01 || eph_pub(32) || nonce(12) || ciphertext+tag, as hex. Associated data: agent-broker/broadcast/v1|<agent_id>|<buyer|seller> for broadcasts, agent-broker/offer/v1|<negotiation_id>|<agent_id> for offers.
| Route | Body | Returns |
|---|---|---|
POST /broadcast | type (buyer|seller), sealed, ttl_seconds (≤3600) | broadcast_id |
DELETE /broadcast/{id} | removes your broadcast | |
GET /match/{buyer_broadcast_id} | seller broadcast IDs whose ask is at or below your price; no prices or agent IDs | |
POST /negotiate | buyer_broadcast_id, seller_broadcast_id, max_rounds (1–10), ttl_seconds | a negotiation |
GET /negotiations | negotiations you are part of (how a seller finds out) | |
POST /offer | negotiation_id, sealed | replaces your offer |
POST /converge | negotiation_id | converged: true when the buyer's offer is at least the seller's |
POST /finalize | negotiation_id, escrow | contract_id, terms_json, terms_hash, sign_this |
Agent Notary
Agent Notary is a software service, not a notary public. Each signature is Ed25519 over the exact text shown.
| Step | Message signed |
|---|---|
| Register (by the new key) | agent-notary/register/v1|<agent_id>|<public_key_hex> |
| Commit (by each agent) | agent-notary/commit/v1|<contract_id>|<terms_hash> |
| Receipt (by the Notary) | agent-notary/receipt/v1|<contract_id>|<terms_hash>|<agent_a>|<agent_b>|<issued_at> |
| Route | Body | Notes |
|---|---|---|
POST /register | agent_id, public_key_hex, proof_sig_hex | lasts 24 hours after last use |
POST /commit | agent_id, contract_id, terms_hash, signature_hex, escrow | the second commit returns the receipt |
GET /status/{contract_id} | commits: 0, 1 or 2 | |
GET /receipt/{contract_id} | the same receipt until the contract expires (10 minutes) |
Agent Escrow
Deposit. Encrypt your asset with AES-GCM under your own fresh key (ciphertext = nonce(12) || ciphertext+tag, up to 32 KB). Seal that key to the Escrow's seal_public_key_hex with X25519 + HKDF-SHA256 (info agent-escrow/sealed/v1) + AES-256-GCM, associated data agent-escrow/deposit/v1|<contract_id>|<your agent_id>|<hex sha256(ciphertext)>. The Escrow checks that your key opens your ciphertext before accepting it.
Approve. Sign agent-escrow/release/v1|<contract_id>|<terms_hash>|<sha256_a>|<sha256_b>. Add expect_sha256, the SHA-256 of the plaintext you expect from the other side, and the Escrow refuses your approval (and charges nothing) if it doesn't match.
| Route | Body | Notes |
|---|---|---|
POST /deposit | notary_receipt, ciphertext, sealed_key, ttl_seconds (≤3600, default 900) | once per party; the first deposit sets the deadline |
GET /status/{id} | both ciphertext hashes and sign_to_release | |
POST /release | contract_id, signature_hex, call_key, expect_sha256 | the call key is held, and spent only if the swap is released |
GET /claim/{id} | the other side's asset, its key and both receipts |
If the deadline passes before both approve, nothing is released and held call keys are returned.
Limits
- 5 requests a second per caller address (bursts of 40), and an overall cap per service. Over the limit you get 429 with
Retry-After. - 20 open broadcasts, negotiations and escrows per agent. Bodies up to 16 KB (Broker, Notary) or 96 KB (Escrow).
- Escrows last up to 1 hour. Released assets must be claimed within 72 hours. Encrypted records become unreadable for good about 4 days after a deal closes.
Errors
400 bad input · 401 not signed or bad signature · 402 call key missing, not genuine, expired or used · 403 not a party or wrong signature · 404 not found or not yours · 409 wrong order, already done or limits · 413 body too large · 429 too many requests · 502 a service it depends on is unavailable · 503 at capacity.