Developer API · Track 2 · B2B

Agent-safe checkout in one call.

ZeroRace exposes a single primitive: POST /v1/purchases/commit — one idempotent ACID transaction on Aurora DSQL that claims inventory, debits a spend mandate, and writes a balanced double-entry ledger, atomically. Drop it into any agent. Retry it forever. It can't oversell, double-charge, or breach a budget.

Quickstart · live sandbox

Run a real commit right now.

No key required. /v1/sandbox/commit runs the exact production kernel against a stocked sandbox SKU and returns a real snapshot from Aurora DSQL. Send it twice with the same Idempotency-Key to watch replay-safety hold.

curl
curl -X POST https://zerorace.vercel.app/v1/sandbox/commit \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: doc-$(uuidgen)" \
  -d '{}'

# → 201 Created
# {
#   "outcome": "COMMITTED",
#   "intentId": "…", "ledgerTxnId": "…",
#   "amountMinor": 2500, "currency": "USD",
#   "attempts": 1, "replayed": false
# }
#
# Re-send with the SAME Idempotency-Key → the byte-identical
# snapshot with "replayed": true. The ledger moves exactly once.
POST /v1/sandbox/commit
LIVE · AURORA DSQL
Integrate

~10 lines in your agent.

typescript
// Your agent settles a purchase. One call. Retry-safe by construction.
const res = await fetch("https://api.zerorace.dev/v1/purchases/commit", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${ZERORACE_API_KEY}`,
    "Idempotency-Key": purchaseId,          // safe to retry forever
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchantId, mandateId, itemId,          // who, which budget, what
    agentId,                                // the acting agent
    quantity: 1,
    amountMinor: 2500, currency: "USD",     // integer minor units, never floats
  }),
});

const settlement = await res.json();
// res.status 201 → COMMITTED (inventory claimed, mandate debited, ledger balanced)
// res.status 200 → DECLINED  (failureCode: OUT_OF_STOCK | MANDATE_REJECTED)
// res.status 409 → same key, different payload (you have a bug — surfaced, not swallowed)
Reference

POST /v1/purchases/commit

The one idempotent ACID commit. Request body:

Field
Type
Meaning
merchantId
uuid
The merchant whose catalog + ledger this settles against.
mandateId
uuid
The agent's spend mandate. The debit and the cap check are one atomic write.
itemId
uuid
The SKU being purchased. Stock is sharded across buckets — no hot row.
agentId
string
The acting agent / principal, recorded on the intent.
quantity
int
Units to claim (≥ 1).
amountMinor
int (BIGINT)
Total amount in minor units (cents). Never a float.
currency
string
ISO currency, e.g. "USD".
Idempotency-Key
header
Header (authoritative) or body field. Same key + same payload → replay.

Response snapshot

Field
Value
outcome
COMMITTED | DECLINED
intentId
uuid of the purchase intent
ledgerTxnId
uuid of the double-entry transaction (COMMITTED only)
chosenBucketId
the inventory shard the unit was claimed from
failureCode
OUT_OF_STOCK | MANDATE_REJECTED (DECLINED only)
attempts
1 + OCC (40001) retries — surfaced, never hidden
replayed
true when served from the idempotency registry

Status codes

Status
Code
Meaning
201
COMMITTED
Inventory claimed, mandate debited, two ledger legs written (net 0).
200
DECLINED
Deterministic business outcome — OUT_OF_STOCK or MANDATE_REJECTED.
409
KEY_REUSED
Same Idempotency-Key, different payload. A caller bug, made loud.
503
RETRY_EXHAUSTED
OCC conflict storm beyond max attempts. Retry the same key.
Why it's safe

Each guarantee is a database invariant.

No oversell
Stock is sharded across random buckets; the claim is a conditional decrement that the DB refuses to take negative. The commit that would oversell loses the OCC race and retries another shard.
No double-charge
Every commit carries an idempotency key under a UNIQUE index. A replay returns the stored snapshot — the ledger moves once, ever.
No mandate breach
The spend cap is read and debited in the same atomic write, against a sharded budget. 0 rows updated → MANDATE_REJECTED, rolled back.
No ledger drift
Every commit writes two legs (−amount / +amount). SUM(signed_amount_minor) = 0 is provable in one query, globally.

// Proven live: a 1,000,000-agent swarm sells exactly 100 units — oversells 0 · duplicate settlements 0 · ledger drift 0 · mandate breaches 0, with OCC retries bounded (585) and visibly non-zero.

See it hold under a million agents.

The same kernel you just called, under a live swarm with a mid-run region failover — every counter pinned at zero.

Enter Mission Control →
ZeroRace · agent-safe checkout kernelAurora DSQL · DynamoDB · Vercel