C3. API & Webhooks
What This Section Is For
EDMA’s API and webhook framework let you plug the platform into your existing systems—ERP, TMS, WMS, ESG—without changing how you work. The API covers the full lifecycle: posting RFQs, awarding orders, funding milestones, submitting/fetching proof, listing/buying/retiring tokens, and reconciling fees and burns. Webhooks notify you in real time when something important happens, so your systems stay up to date automatically.
Access & Safety (The Basics)
Auth: OAuth2 client credentials for API calls; HMAC-SHA256 signatures for webhooks.
Replay protection: Every webhook includes edma-timestamp and edma-signature; reject if clock-skew exceeds 5 minutes or signature is invalid.
Idempotency: Use Idempotency-Key header on POSTs that change state; retries are safe.
Versioning: Endpoints are prefixed with /v1; breaking changes ship under /v2 with deprecation windows.
Rate limits: 600 requests/minute/org (burstable); standard 429 with Retry-After on limit.
Privacy: PoV evidence files live off-chain under access control; chain stores hashes. API returns signed, expiring URLs; webhooks never include sensitive blobs.
What You Can Do (High Level)
Trade Rail:
Post RFQs and bids; award suppliers.
Prefund milestones; top-up remaining; fetch stage coverage and Locked EDSD by supplier.
Submit proof (attestors), read gate status, receive milestone releases when EMTs mint.
Open/resolve exceptions; attach re-inspection and variance outcomes.
Create funded-on-proof assignments; redeem Unlocked EDSD off-platform at schedule completion.
Tokens Rail:
List PoV-verified tokens; freeze/unfreeze on proof change.
Settle buys/retirements; fetch receipts and burn hashes.
Pull portfolio and proof packs for audit/ESG.
The Endpoints You’ll Actually Call (By Job)
RFQ → Award (Trade):
POST /v1/trade/rfqs — create RFQ
POST /v1/trade/rfqs/{rfq_id}/bids — suppliers bid
POST /v1/trade/awards — compose winning mix; returns MPA with schedules/checklists
Fund → Coverage (Trade):
POST /v1/trade/orders/{order_id}/prefund — wire notice + amount; mints Locked EDSD
POST /v1/trade/orders/{order_id}/topup — fund remaining milestones
GET /v1/trade/orders/{order_id}/coverage — stage/supplier coverage, EDSD totals, top-up deadlines
Proof → EMT → Release (Trade):
POST /v1/trade/proof/{order_id}/{stage} — attestors upload/confirm evidence
GET /v1/trade/orders/{order_id}/stages — gate state, review windows, exception refs
GET /v1/trade/releases/{release_id} — release receipt: amount, burn hash, fee split, proof page URL
Exceptions (Trade):
POST /v1/trade/exceptions — open a case
POST /v1/trade/exceptions/{case_id}/resolve — resolve case per MPA rules
GET /v1/trade/exceptions/{case_id} — case pack: checklist, files, timeline, variance math, decision
Assignments & Cash-Out (Trade):
POST /v1/trade/assignments — funded-on-proof assignment (1% fee when milestone passes)
POST /v1/trade/cashout — off-platform redemption (0.5% fee at completion)
GET /v1/trade/ledger/{order_id} — per-order ledger: protocol fee, burns, assignment/cash-out fees, treasury interest
Tokens:
POST /v1/tokens/listings — list PoV-verified tokens
POST /v1/tokens/settle — buy/retire; 50% burn in EDM
GET /v1/tokens/receipts/{id} — receipt, proof pack, burn hash, treasury half
Webhooks (What You’ll Subscribe To)
Trade — milestones & money: milestone passed, release posted, milestone blocked, pending funds, slice frozen/unfrozen, exception opened/resolved, assignment settled, cashout redeemed.
Tokens — settlements & retirements: listing frozen/unfrozen, settlement posted, retirement proofpack ready.
Fee & treasury: fee burn posted, treasury interest accrued.
Example Payloads (Trimmed for Clarity)
trade.milestone.passed
{
"id": "evt_9fK2",
"type": "trade.milestone.passed",
"order_id": "ord_72ab",
"stage": "ON_BOARD",
"emt_id": "emt_3cd9",
"supplier_id": "sup_shanghai_01",
"lots": ["lot_001","lot_002"],
"evidence": {
"bl_number": "OOLU1234567890",
"seal_number": "SEAL9981",
"seal_photo_url": "https://signed.edma/files/seal_9981.jpg",
"hash": "0x9a7d…"
},
"occurred_at": "2025-01-12T14:20:02Z"
}trade.release.posted
{
"id": "evt_a1b2",
"type": "trade.release.posted",
"order_id": "ord_72ab",
"stage": "ON_BOARD",
"slice": {
"locked_edsd": "3960000.00",
"unlocked_edsd": "3960000.00"
},
"recipient": { "supplier_id": "sup_shanghai_01" },
"fee": {
"protocol_fee": "19800.00",
"burn_in_edm": "9900.00",
"treasury_half": "9900.00",
"cap_applied": false
},
"burn": { "token": "EDM", "tx_hash": "0x6c73…" },
"occurred_at": "2025-01-12T14:20:04Z"
}tokens.settlement.posted
{
"id": "evt_tk88",
"type": "tokens.settlement.posted",
"listing_id": "lst_55aa",
"action": "BUY",
"quantity": "100.0",
"price_edsd": "18.00",
"fee": { "total_pct": 4.0, "buyer_pct": 2.0, "seller_pct": 2.0 },
"burn": { "amount_edm": "42.50", "tx_hash": "0x5ab1…" },
"proof": { "pov_badge": true, "one_claim_ref": "ocl_7f4d" },
"occurred_at": "2025-01-08T09:33:12Z"
}Good Citizen Guidelines
Map events to actions: update ERP, TMS, WMS, ESG from webhooks.
Keep idempotency keys for award, prefund, top-up, proof, exception, assignment, cash-out.
Store proof links and hashes for audit.
Test in sandbox: same API, slower clocks, fake evidence; flip credentials for production.
Plain Recap
Last updated