{"openapi":"3.1.0","info":{"title":"Forge API","version":"0.1.0-lite","description":"Private OTC block trades. No accounts: creating a posting or answer returns a capability token; send it as `Authorization: Bearer <token>`. Answers are sealed client-side; the server stores ciphertext only. Settlement happens on-chain in the OtcEscrow contract."},"servers":[{"url":"https://api.forgetrade.sbs"}],"components":{"schemas":{"RfqCreate":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"side":{"type":"string","enum":["buy","sell"]},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"payToken":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"sizeUsd":{"type":"string","pattern":"^\\d{1,15}(\\.\\d{1,6})?$"},"note":{"type":"string","maxLength":280},"encPubKey":{"type":"string","pattern":"^[A-Za-z0-9+/_-]+={0,2}$"},"replyWindow":{"type":"string","enum":["15m","1h","4h","6h","24h"]},"allowPartial":{"default":false,"type":"boolean"}},"required":["side","token","payToken","amount","encPubKey","replyWindow"]},"RfqPublic":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"payToken":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"filledAmount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"sizeUsd":{"type":["string","null"]},"note":{"type":["string","null"]},"encPubKey":{"type":"string"},"allowPartial":{"type":"boolean"},"status":{"type":"string","enum":["open","filled","cancelled","expired"]},"quoteCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["id","side","token","payToken","amount","filledAmount","sizeUsd","note","encPubKey","allowPartial","status","quoteCount","createdAt","expiresAt"]},"SealedQuoteCreate":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"senderEncPubKey":{"type":"string","pattern":"^[A-Za-z0-9+/_-]+={0,2}$"},"nonce":{"type":"string","pattern":"^[A-Za-z0-9+/_-]+={0,2}$"},"ciphertext":{"type":"string","pattern":"^[A-Za-z0-9+/_-]+={0,2}$"}},"required":["senderEncPubKey","nonce","ciphertext"]},"Terms":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"buyer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"seller":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"payToken":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"price":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"sellerPayout":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"referrer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"relayerFee":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"deadline":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"salt":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["buyer","seller","token","amount","payToken","price","sellerPayout","referrer","relayerFee","deadline","salt"]},"AcceptBody":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quoteId":{"type":"string","minLength":1,"maxLength":64},"terms":{"type":"object","properties":{"buyer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"seller":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"payToken":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"price":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"sellerPayout":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"referrer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"relayerFee":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"deadline":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"salt":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["buyer","seller","token","amount","payToken","price","sellerPayout","referrer","relayerFee","deadline","salt"]}},"required":["quoteId","terms"]},"SettledReport":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"txHash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["txHash"]},"RelayDepositBody":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"terms":{"type":"object","properties":{"buyer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"seller":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"token":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"payToken":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"price":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"sellerPayout":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"referrer":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$"},"relayerFee":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"deadline":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"salt":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["buyer","seller","token","amount","payToken","price","sellerPayout","referrer","relayerFee","deadline","salt"]},"permit":{"anyOf":[{"type":"object","properties":{"value":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"deadline":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"v":{"type":"integer","minimum":27,"maximum":28},"r":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"s":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"}},"required":["value","deadline","v","r","s"]},{"type":"null"}]},"authDeadline":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"signature":{"type":"string","pattern":"^0x[0-9a-fA-F]{130}$"}},"required":["terms","permit","authDeadline","signature"]},"Subscribe":{"$schema":"https://json-schema.org/draft/2020-12/schema","oneOf":[{"type":"object","properties":{"capability":{"type":"object","properties":{"kind":{"type":"string","enum":["rfq","quote"]},"id":{"type":"string","pattern":"^[0-9A-Z]{26}$"}},"required":["kind","id"]},"channel":{"type":"string","const":"telegram"},"destination":{"type":"string","pattern":"^-?\\d{1,20}$"}},"required":["capability","channel","destination"]},{"type":"object","properties":{"capability":{"type":"object","properties":{"kind":{"type":"string","enum":["rfq","quote"]},"id":{"type":"string","pattern":"^[0-9A-Z]{26}$"}},"required":["kind","id"]},"channel":{"type":"string","const":"email"},"destination":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["capability","channel","destination"]},{"type":"object","properties":{"capability":{"type":"object","properties":{"kind":{"type":"string","enum":["rfq","quote"]},"id":{"type":"string","pattern":"^[0-9A-Z]{26}$"}},"required":["kind","id"]},"channel":{"type":"string","const":"webhook"},"destination":{"type":"string","maxLength":2048,"format":"uri"}},"required":["capability","channel","destination"]}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["VALIDATION_FAILED","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","RATE_LIMITED","IDEMPOTENCY_CONFLICT","RFQ_NOT_FOUND","RFQ_EXPIRED","RFQ_CLOSED","RFQ_FULLY_FILLED","QUOTE_NOT_FOUND","QUOTE_TOO_LARGE","QUOTE_ALREADY_ACCEPTED","TERMS_MISMATCH","SIG_INVALID","DEAL_NOT_FOUND","TX_NOT_FOUND","TX_NOT_SETTLEMENT","TOKEN_NOT_CONTRACT","UNSUPPORTED_PAY_TOKEN","RELAY_FEE_TOO_LOW","RELAY_SIMULATION_FAILED","UPSTREAM_UNAVAILABLE","INTERNAL"]},"message":{"type":"string"},"requestId":{"type":"string"},"problems":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}}},"securitySchemes":{"manageToken":{"type":"http","scheme":"bearer","description":"Capability token returned by POST /rfqs"},"quoteToken":{"type":"http","scheme":"bearer","description":"Capability token returned by POST /rfqs/{id}/quotes"}}},"paths":{"/health":{"get":{"summary":"Server config and dependency health","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs":{"get":{"summary":"Open bids and listings (public view, never prices)","tags":["desk"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Post a bid (side=buy) or listing (side=sell); returns a manage token once","tags":["desk"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RfqCreate"}}}},"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}":{"get":{"summary":"One posting (public view)","tags":["desk"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}/cancel":{"post":{"summary":"Cancel your posting","tags":["desk"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"manageToken":[]}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}/quotes":{"get":{"summary":"Sealed answers on your posting (ciphertext)","tags":["desk"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"manageToken":[]}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Send a sealed answer; returns a quote token once","tags":["desk"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SealedQuoteCreate"}}}},"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}/accept":{"post":{"summary":"Accept one answer and fix the deal terms","tags":["deals"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"security":[{"manageToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptBody"}}}},"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}/deal":{"get":{"summary":"Latest accepted deal","tags":["deals"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"manageToken":[]}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}/deals":{"get":{"summary":"Every deal on a posting (partial fills)","tags":["deals"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"manageToken":[]}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rfqs/{id}/settled":{"post":{"summary":"Report the settlement tx; verified on-chain first","tags":["deals"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettledReport"}}}},"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes/{id}":{"get":{"summary":"Your answer's status; terms once accepted","tags":["deals"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"quoteToken":[]}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deals/{dealId}/receipt":{"get":{"summary":"Settlement tx of a deal, once reported","tags":["deals"],"parameters":[{"name":"dealId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/receipts/{tx}":{"get":{"summary":"Public receipt rebuilt from the settlement transaction","tags":["deals"],"parameters":[{"name":"tx","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/relay":{"get":{"summary":"Relayer address and minimum fee","tags":["ghost"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/relay/deposit":{"post":{"summary":"Ghost mode: queue a relayed delivery","tags":["ghost"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelayDepositBody"}}}},"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/relay/requests/{id}":{"get":{"summary":"Relay request status","tags":["ghost"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/token/{address}":{"get":{"summary":"ERC-20 facts read on-chain","tags":["market"],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/token/{address}/market":{"get":{"summary":"DEX snapshot (reference only)","tags":["market"],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/price/{token}":{"get":{"summary":"Latest DEX price (reference only)","tags":["market"],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets":{"get":{"summary":"Featured markets with delayed reference prices and open blocks","tags":["market"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/markets/{symbol}/chart":{"get":{"summary":"OHLC candles of the reference listing (delayed)","tags":["market"],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/burn":{"get":{"summary":"Buy-and-burn vault state: route, queued route + ETA, burned totals","tags":["stats"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/control":{"get":{"summary":"Live control panel read from the chain: escrow, fee vault roles, burn route, balances, relayer","tags":["stats"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"summary":"Desk totals checked against the escrow","tags":["stats"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/referrals/{address}":{"get":{"summary":"Referred deals and earnings","tags":["stats"],"parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notifications":{"get":{"summary":"Channels subscribed for a posting or answer","tags":["realtime"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Subscribe Telegram, email or webhook alerts to a posting or answer","tags":["realtime"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscribe"}}}},"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notifications/remove":{"post":{"summary":"Unsubscribe a channel","tags":["realtime"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/notifications/test":{"post":{"summary":"Send one test alert to every channel on a posting or answer (3 per 10 min)","tags":["realtime"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sdk/forge.mjs":{"get":{"summary":"Bundled JavaScript SDK (ES module); SHA-256 in x-content-sha256","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sdk/forge.mjs.sha256":{"get":{"summary":"SHA-256 of the SDK bundle","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp/forge-mcp.mjs":{"get":{"summary":"Single-file MCP server for AI agents (run with node 22+); SHA-256 in x-content-sha256","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/mcp/forge-mcp.mjs.sha256":{"get":{"summary":"SHA-256 of the MCP server bundle","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/site":{"get":{"summary":"Public site settings: the token contract address (CA) set by the operator","tags":["meta"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stream":{"get":{"summary":"Server-Sent Events: desk, rfq:<id> (manage token), quote:<id> (quote token)","tags":["realtime"],"parameters":[],"responses":{"200":{"description":"OK"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}