API & tiers
Scope:
This page defines the public API surface (Tokens & Trade), auth/webhooks/versioning rules, error codes, and the tier framework (Buyers B0–B2, Sellers S0–S2, Tokens T0–T2): Tiers are earned, not bought, and improve clocks and limits—never the law.
No EMT, no funds:
Must-fund before shipping:
One-Claim uniqueness:
Locked EDSD → Unlocked EDSD only on proof:
50% of every protocol fee burns in EDM (at event):
A) API — Foundations
Auth & security:
OAuth2 client-credentials (per org) for REST: HMAC-SHA256 signatures on webhooks (edma-timestamp, edma-signature).
Idempotency on all mutating POSTs via Idempotency-Key: Retries are safe.
Rate limits: default 600 req/min/org, burstable; 429 + Retry-After.
Versioning: /v1 stable; breaking changes in /v2; deprecation windows announced via gov.param.changed.
Privacy: raw evidence never in webhooks; signed URLs (short-lived, IP-scoped) retrieved via API.
Sandbox: same interface under a separate base URL; slower clocks, test attestations.
Common errors: E_CANONICAL_DRIFT · E_FORMAT_INVALID · E_SET_NOT_SORTED · E_FILE_MISSING · E_HASH_MISMATCH · E_QUORUM_MISSING · E_STALE_ATTEST · E_KEY_REVOKED · E_PENDING_FUNDS · E_ONECLAIM_TAKEN · E_LISTING_FROZEN
B) API — Tokens
Books & orders:
GET /v1/tokens/books?symbol=CARB.VERRA.AMR.2027: top-of-book, depth, 24h vol
POST /v1/tokens/orders: { symbol, side, qty, limit, tif, max_slippage_bps? }
DELETE /v1/tokens/orders/{id}: GET /v1/tokens/orders?status=open|filled
Mint / settle / retire:
POST /v1/tokens/mint: { schema_id, dossierBytes, attestorBundle } → { token_id, claim_id }
POST /v1/tokens/settle: { order_id } → fills trade; fee 4%; 50% burn; returns { fee, burnHash }
POST /v1/tokens/retire: { token_id, beneficiary?, purpose? } → retirement; fee 4%; 50% burn
Mirrors:
POST /v1/registry/mirrors (registry role): { program, serial, claim_id, pov_hash, registrySig }
POST /v1/registry/mirrors/{id}/revoke|replace (registry role):
Webhooks:
tokens.settlement.posted: { price, qty, fee, burnHash }
tokens.retirement.proofpack.ready:
tokens.listing.frozen|unfrozen: (reason)
fee.burn.posted: (cross-rail)
C) API — Trade
RFQ & bids:
POST /v1/trade/rfqs: { spec, incoterm, route, milestones, schemas, schedule, topup_deadlines }
POST /v1/trade/rfqs/{id}/bids: { price, fillable_pct, ready_window, compliance }
POST /v1/trade/awards: { rfq_id, allocations[] } → returns MPA id + per-stage Locked EDSD pre-assignments (fee escrow pre-paid)
Proof & release:
POST /v1/trade/proof/{order_id}/{stage}: { schema_id, dossierBytes, attestorBundle } → { pass|fail, gate_pass_id?, reason }
POST /v1/trade/release/{order_id}/{stage}: { gate_pass_id } → flips Locked→Unlocked; charges 0.5% (capped); burn 50%; { amountEdsd, fee, burnHash }
Exceptions & replacements:
POST /v1/exceptions/{case_id}/variance: (apply variance table)
POST /v1/trade/replace: (mint corrective EMT; replaces: old_claim_id)
POST /v1/pov/revoke: (role/registry only)
Ledger & PoR:
GET /v1/trade/contracts/{id}: coverage by stage, Locked/Unlocked, fee-escrow balance, next top-up
GET /v1/por/daily: latest snapshot (hash + signed URL)
Webhooks:
trade.milestone.passed → trade.release.posted: { amountEdsd, fee, burnHash }
trade.slice.frozen|unfrozen:
pov.attestation.revoked:
exceptions.case.updated:
sla.revocation.breached:
D) Tiers — Why they exist
Tiers speed you up (shorter clocks, higher limits) as your record improves: they never bypass admissibility or burn rules.
Buyers (Trade): B0 → B2 (review window, top-up clocks, open-order caps)
Sellers (Trade): S0 → S2 (assignment caps, cash-out speed, credit eligibility)
Tokens participants: T0 → T2 (API quotas, batch endpoints, custodian features)
Upgrade/downgrade: rolling window KPIs; programmatic—no manual intervention.
E) Buyer Tiers
Tier
Review window
Top-up deadline (pre-On-Board)
Open-order cap
Notes
B0 — New
up to 4h
T−48h
conservative
Prefund first milestone + buffer; must-fund before shipping
B1 — Proven
up to 2h
T−24h
higher
Fewer false-blocks; Pending Funds rare
B2 — Trusted
up to 1h
T−12h (or JIT where governed)
highest
Eligible for JIT Top-Up Bridge (if enabled)
Promotion conditions (90d rolling):
Top-up SLA breaches ≤ 1% of gates:
False-block rate ≤ 1%:
Disputes / 100 gates ≤ 3:
No sanctions/KYC flags; clean payment history:
Downgrade if any exceeds thresholds for 30d.
F) Seller Tiers
Tier
Assignment cap (funded-on-proof)
Cash-out
Credit
S0 — New
30% of Locked EDSD
T+1 after schedule completion
—
S1 — Proven
60%
T+0
Supplier Advance eligible (3–4% APR)
S2 — Trusted
90%
T+0 priority
Larger credit line; fast-track exceptions
Promotion conditions (90d rolling):
Docs on time; revocations ≤ 1%; exception closure p95 ≤ 72h; cold-chain compliance ≥ 99% where applicable.
Clean KYC/KYB; low variance deltas.
G) Tokens Participant Tiers (T0–T2)
Tier
API quota
Features
T0 — Standard
600 req/min
REST + webhooks; manual listing/retirement
T1 — Pro
1,200 req/min
Batch orders/retirements; portfolio API; custodian support
T2 — Institutional
3,000 req/min
Full portfolio APIs; sub-accounts; maker RFQ endpoints; cold-storage flows
Upgrade by 60d volume + clean compliance; downgrade on abuse (wash-trade, freeze events).
H) SLA & KPIs for tiers
Buyers: top-up SLA breaches, false-block rate, disputes, sanctions status.
Sellers: revocation rate, exception resolution time, latency to submit proof, cold-chain compliance, assignment usage.
Tokens: listing freezes, revocation hits, settlement throughput.
KPIs are visible in Explorer (org dashboards); tier changes are announced via email + API (/v1/org/tier).
I) Governance & safety rails
Governance can tune tier bounds (review window range, assignment caps, top-up deadlines), API quotas, and promotion formulas—within ParameterStore bounds and with 72h timelock.
Governance cannot relax settlement law, fee constants/caps, One-Claim, must-fund, or the 50% burn.
Transparency: changes emit gov.param.changed; clients can query /v1/gov/params to sync.
J) Developer ergonomics
Schemas & test vectors: GET /v1/schemas, /v1/schemas/{id}/examples (canonical fixtures)
SDKs (TS/Python): canonicalizer, dossier validator, claimId & Merkle helpers, webhook verifier
Receipts: every value-realizing event includes PoV hash, claim id, burn hash, and net flows; CSV exports per order/listing
Plain recap
Last updated