{"openapi":"3.1.0","info":{"title":"UnyKorn Intake Desk API","version":"1.0.0","description":"Partner API for brokers (deals, documents, inbox) and operator endpoints. Nothing submitted is treated as proof of funds. Every submission is an unverified document record until the holding bank attests bank-to-bank."},"servers":[{"url":"https://desk.3fs.app"}],"security":[{"brokerKey":[]}],"components":{"securitySchemes":{"brokerKey":{"type":"http","scheme":"bearer","description":"Broker API key (dk_…), issued once by the operator. Rate limit 120 requests/minute/key."}},"schemas":{"Intake":{"type":"object","required":["entity","contact_name","contact_email","stated_amount","currency","holding_bank"],"properties":{"entity":{"type":"string","maxLength":4000},"jurisdiction":{"type":"string","maxLength":4000},"registration_number":{"type":"string","maxLength":4000},"contact_name":{"type":"string","maxLength":4000},"contact_role":{"type":"string","maxLength":4000},"contact_email":{"type":"string","maxLength":4000},"stated_amount":{"type":"string","maxLength":4000},"currency":{"type":"string","maxLength":4000},"holding_bank":{"type":"string","maxLength":4000},"account_name":{"type":"string","maxLength":4000},"manager_of_record":{"type":"string","maxLength":4000},"source_of_funds":{"type":"string","maxLength":4000},"goal":{"type":"string","maxLength":4000},"holders":{"type":"string","maxLength":4000},"counsel":{"type":"string","maxLength":4000},"tranche_program":{"type":"string","maxLength":4000},"stablecoin_leg":{"type":"string","maxLength":4000},"broker_reference":{"type":"string","maxLength":4000}}},"Deal":{"type":"object","properties":{"id":{"type":"string","example":"DL-2026-0007"},"status":{"type":"string","enum":["INTAKE","DOCUMENTS","SCREENING","ATTESTATION_REQUESTED","VERIFIED","FORWARDED","TOKENIZED","SETTLED","DECLINED"]},"broker_id":{"type":"string"},"data":{"$ref":"#/components/schemas/Intake"},"gate":{"type":"array","items":{"$ref":"#/components/schemas/GateItem"}},"screening":{"type":"object","nullable":true},"attestation":{"type":"object","nullable":true},"forward":{"type":"object","nullable":true},"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentRecord"}},"events":{"type":"array","items":{"type":"object"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"GateItem":{"type":"object","properties":{"id":{"type":"string","example":"g1"},"title":{"type":"string"},"satisfiedBy":{"type":"string"},"status":{"type":"string","enum":["required","received","verified","waived","failed"]},"note":{"type":"string"}}},"DocumentRecord":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"size":{"type":"integer"},"mime":{"type":"string"},"label":{"type":"string","example":"unverified document record"},"created_at":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","unprocessable","rate_limited","upstream_error","not_configured"]},"request_id":{"type":"string"}}},"WebhookEvent":{"type":"object","description":"Signed with x-desk-timestamp and x-desk-signature (sha256=HMAC_SHA256(secret, `${timestamp}.${raw_body}`)).","properties":{"event":{"type":"string","example":"deal.verified"},"deal_id":{"type":"string"},"status":{"type":"string"},"broker_id":{"type":"string"},"at":{"type":"string","format":"date-time"}}}}},"paths":{"/api/v1/health":{"get":{"security":[],"summary":"Liveness and configuration flags","responses":{"200":{"description":"ok"}}}},"/api/v1/deals":{"post":{"summary":"Open a deal file","description":"Send Idempotency-Key to make retries safe; the same key from the same caller returns the original deal.","parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Intake"}}}},"responses":{"200":{"description":"idempotent replay"},"201":{"description":"created","content":{"application/json":{"schema":{"type":"object","properties":{"deal":{"$ref":"#/components/schemas/Deal"},"next":{"type":"object"}}}}}},"401":{"description":"missing or revoked key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}":{"get":{"summary":"Read a deal (own deals only)","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"deal","content":{"application/json":{"schema":{"type":"object","properties":{"deal":{"$ref":"#/components/schemas/Deal"}}}}}},"403":{"description":"not your deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"unknown deal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/documents":{"post":{"summary":"Record a document","description":"multipart/form-data with `file` (hashed server-side, bytes discarded) or JSON {name, sha256, size, mime}.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"recorded"},"400":{"description":"bad hash or missing name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/inbox":{"post":{"summary":"Drop raw files (JSON kept, others hashed)","description":"multipart/form-data with any file fields and optional `note`, or a raw JSON body with headers x-file-name and x-note.","responses":{"201":{"description":"received"}}}},"/api/v1/agent/intake":{"post":{"summary":"Intake assistant turn","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"reply and optional draft"},"503":{"description":"assistant not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/next":{"get":{"summary":"Next step for a deal","description":"Deterministic guidance: what is owed, by whom, and what to say. Also returned as `next` on GET /deals/{id}.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"step"}}}},"/api/v1/guide":{"get":{"summary":"Desk guide (operator)","description":"Ranked next moves across every open deal, funnel, verified rate, coaching lines.","responses":{"200":{"description":"guide"}}}},"/api/v1/agent/guide":{"post":{"summary":"AI guide turn (operator)","description":"Coaching assistant that sees the whole desk. Needs ANTHROPIC_API_KEY on the Worker.","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"history":{"type":"array"}}}}}},"responses":{"200":{"description":"reply"},"503":{"description":"not configured"}}}},"/api/v1/market":{"get":{"summary":"Live XRP/RLUSD book and AMM (operator)","description":"Best bid/ask, sizes, microprice, spread, AMM reserves and pool price from the XRP Ledger mainnet, plus the formula list.","responses":{"200":{"description":"market"}}}},"/api/v1/bots":{"get":{"summary":"Paper bots (operator)","description":"Avellaneda-Stoikov maker, grid maker and AMM-vs-book arbitrage, all paper. Equity, P&L, fills, Sharpe, drawdown, VaR. No live execution exists in this build.","responses":{"200":{"description":"bots"}}}},"/api/v1/bots/tick":{"post":{"summary":"Run one paper tick now (operator)","responses":{"200":{"description":"results"}}}},"/api/v1/bots/{id}/{action}":{"post":{"summary":"toggle | reset | params | go-live (operator)","description":"go-live only queues a principal approval; nothing trades without a signing executor and a funded account.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"action","required":true,"schema":{"type":"string","enum":["toggle","reset","params","go-live"]}}],"responses":{"200":{"description":"bot"},"202":{"description":"approval queued"}}}},"/api/v1/brokers/{id}/chain":{"post":{"summary":"Set a broker's payout chain (operator)","description":"Up to 8 introducers, flat USD each, never a percentage. Mirrors FeeEscrow.fundWithChain: broker fee and every link pay out in one transaction at milestone M1.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","example":"BR-001"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chain":{"type":"array","maxItems":8,"items":{"type":"object","required":["name","flat_usd"],"properties":{"name":{"type":"string"},"address":{"type":"string","description":"USDC payout wallet"},"flat_usd":{"type":"integer","minimum":0}}}}}}}}},"responses":{"200":{"description":"broker + contract call"},"422":{"description":"too long or not flat"}}}},"/api/v1/track":{"get":{"security":[],"summary":"Client tracker (public)","description":"Plain-words status for a file. ref is a submission (S-12) or a deal (DL-2026-0012); code is the tracking code given on upload or by the desk. 30 lookups per minute per IP.","parameters":[{"in":"query","name":"ref","required":true,"schema":{"type":"string"}},{"in":"query","name":"code","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"status, documents with CIDs, Merkle receipt"},"404":{"description":"no match"},"429":{"description":"slow down"}}}},"/api/v1/deals/{id}/receipt":{"get":{"summary":"Trust receipt","description":"SHA-256 per document, IPFS CIDv1 (raw, sha2-256) per document, Merkle root over the file set with a proof per document (RFC 6962 shape). Computed, not pinned.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"receipt"}}}},"/api/v1/webhooks/verify-example":{"get":{"security":[],"summary":"How to verify a desk webhook signature","responses":{"200":{"description":"scheme"}}}}},"x-webhooks":{"events":["deal.created","deal.documents","deal.attestation_requested","deal.verified","deal.forwarded","deal.declined","deal.tokenized","deal.settled","deal.stale"],"delivery":"POST to the broker's webhook_url, JSON body, headers x-desk-timestamp, x-desk-signature, x-desk-signature-version: v2","retry":"none; poll GET /api/v1/deals/{id} as the source of truth"}}