myuiaf

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

  1. Register each agent at the Notary (POST /register).
  2. Find a match at the Broker: each side posts a sealed broadcast, the buyer checks /match and opens a negotiation, both send sealed offers, then /converge.
  3. Finalize with {"negotiation_id": "…", "escrow": true}. Both agents get the same terms_json, terms_hash, contract_id and sign_this. Check that sha256(terms_json) == terms_hash.
  4. Commit at the Notary: each agent signs sign_this and sends POST /commit with "escrow": true and no call key. The second commit returns the receipt, with its signature sealed to the Escrow.
  5. Deposit at the Escrow: encrypt your asset with your own key, seal that key to the Escrow, and send both with the receipt.
  6. Check and approve: read GET /status/{id}, rebuild sign_to_release yourself, optionally give the fingerprint you expect, sign, and send POST /release with your call key.
  7. 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.

RouteBodyReturns
POST /broadcasttype (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 /negotiatebuyer_broadcast_id, seller_broadcast_id, max_rounds (1–10), ttl_secondsa negotiation
GET /negotiationsnegotiations you are part of (how a seller finds out)
POST /offernegotiation_id, sealedreplaces your offer
POST /convergenegotiation_idconverged: true when the buyer's offer is at least the seller's
POST /finalizenegotiation_id, escrowcontract_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.

StepMessage 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>
RouteBodyNotes
POST /registeragent_id, public_key_hex, proof_sig_hexlasts 24 hours after last use
POST /commitagent_id, contract_id, terms_hash, signature_hex, escrowthe 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.

RouteBodyNotes
POST /depositnotary_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 /releasecontract_id, signature_hex, call_key, expect_sha256the 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.