{ "openapi": "3.1.0", "info": { "title": "Zornado swap API", "version": "1.0.0", "description": "Native HTTP swaps. No API account or API key. Discover executable pairs before quoting: XMR may be unavailable and ZEC can be payout-only. An order creates a financial commitment; use operator-authorized limits and save exact requests before acceptance. Referrals are optional and deployment-gated; credits are not automatic cash payments." }, "servers": [ { "url": "/" } ], "paths": { "/api/v1/route/status": { "get": { "operationId": "discoverSwaps", "summary": "Discover current executable pairs and intake status", "responses": { "200": { "description": "Require quotingAvailable and acceptingOrders before new acceptance. Only advertised exact pairs are executable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "quotingAvailable", "acceptingOrders", "pairs" ], "properties": { "mode": { "enum": [ "execution", "quote-only" ] }, "quotingAvailable": { "type": "boolean" }, "acceptingOrders": { "type": "boolean" }, "pairs": { "type": "array", "items": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "object", "required": [ "asset", "network" ], "properties": { "asset": { "type": "string", "examples": [ "BTC", "ETH", "XMR", "ZEC" ] }, "network": { "type": "string", "examples": [ "bitcoin", "ethereum", "monero", "zcash" ] } }, "additionalProperties": false }, "to": { "type": "object", "required": [ "asset", "network" ], "properties": { "asset": { "type": "string", "examples": [ "BTC", "ETH", "XMR", "ZEC" ] }, "network": { "type": "string", "examples": [ "bitcoin", "ethereum", "monero", "zcash" ] } }, "additionalProperties": false } } } }, "referrals": { "type": "object", "properties": { "enabled": { "const": true }, "shareBps": { "const": 2000 }, "asset": { "const": "ZEC" }, "payout": { "const": "approval-required" } } } } } } } } } } }, "/api/v1/route/quotes": { "post": { "operationId": "quoteSwap", "summary": "Request a signed estimate and minimum payout", "description": "Amounts/networks/addresses/referral must match the authorized request. Quote expires within 60s. Providers can receive both addresses during quoting. Preserve the returned object unchanged; the settlement rate can vary. minAmountOut is the signed floor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "amountIn", "payoutAddress", "refundAddress" ], "properties": { "from": { "$ref": "#/components/schemas/Asset" }, "to": { "$ref": "#/components/schemas/Asset" }, "amountIn": { "$ref": "#/components/schemas/Units" }, "payoutAddress": { "type": "string", "maxLength": 512 }, "refundAddress": { "type": "string", "maxLength": 512 }, "referralCode": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } } } } } }, "responses": { "200": { "description": "Signed quote including optional signed referral terms.", "content": { "application/json": { "schema": { "type": "object", "required": [ "routeQuoteId", "from", "to", "via", "leg1", "leg2", "fee", "minAmountOut", "expiresAt", "signature" ] } } } }, "400": { "description": "Invalid input or unavailable pair.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Unavailable; retry with backoff.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/orders": { "post": { "operationId": "acceptSwap", "summary": "Accept once using a persisted random idempotency key", "description": "Persist the complete exact body BEFORE posting. A timeout does not prove rejection. Replay the identical body and key to recover, including after expiry or when intake is paused. Never generate a replacement key while outcome is uncertain.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "routeQuote", "payoutAddress", "refundAddress", "idempotencyKey" ], "properties": { "routeQuote": { "type": "object", "description": "Complete unmodified signed quote from quoteSwap." }, "payoutAddress": { "type": "string" }, "refundAddress": { "type": "string" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Cryptographically random; persist before posting." } } } } } }, "responses": { "201": { "description": "Save routeId and routeToken privately. Deposit may follow on polling.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Same key with different request: reconcile, do not send again.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Unknown outcome or stopped intake; replay exact saved request.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/orders/{routeId}": { "get": { "operationId": "trackSwap", "summary": "Read order state without advancing execution", "security": [ { "RouteToken": [] } ], "parameters": [ { "name": "routeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Private order or signed receipt. Save receipt immediately at completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown order or invalid capability.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Receipt requested before terminal state.", "content": { "application/json": { "schema": { "type": "object" } } } }, "410": { "description": "Verified completed/refunded order purged after 72h; receipt no longer available.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/orders/{routeId}/receipt": { "get": { "operationId": "getReceipt", "summary": "Download the signed terminal receipt", "security": [ { "RouteToken": [] } ], "parameters": [ { "name": "routeId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "responses": { "200": { "description": "Private order or signed receipt. Save receipt immediately at completion.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown order or invalid capability.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Receipt requested before terminal state.", "content": { "application/json": { "schema": { "type": "object" } } } }, "410": { "description": "Verified completed/refunded order purged after 72h; receipt no longer available.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/referrals": { "get": { "operationId": "referralProgram", "summary": "Read referral activation and terms", "responses": { "200": { "description": "Disabled, or 20% of net Zornado service fee as ZEC credits. withdrawals=true enables authenticated requests; every send still needs signed operator approval.", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "openReferralAccount", "summary": "Create or recover the same referral account with a saved key", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recoveryKey" ], "properties": { "recoveryKey": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "32 random bytes as lowercase hex; save privately before posting, never in URLs." } } } } } }, "responses": { "200": { "description": "Shareable public code; same saved key recovers same account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } } } } } }, "503": { "description": "Program disabled or capacity reached.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/referrals/{code}": { "get": { "operationId": "getReferralBalance", "summary": "Read aggregate earned credit using your private key", "security": [ { "ReferralKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "Aggregate earned credit; when withdrawals are enabled, paid includes the actual fee, held includes the maximum fee, and available excludes both.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "asset", "earnedZat", "shareBps" ], "properties": { "code": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" }, "asset": { "const": "ZEC" }, "earnedZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "shareBps": { "const": 2000 }, "paidZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "heldZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "availableZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } }, "404": { "description": "Unknown account or invalid key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Program disabled.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/referrals/{code}/withdrawals": { "get": { "operationId": "listReferralWithdrawals", "summary": "Recover up to 20 recent withdrawals, pending first", "security": [ { "ReferralKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "Only this account; pending counts all unfinished requests.", "content": { "application/json": { "schema": { "type": "object", "required": [ "withdrawals", "pending" ], "properties": { "withdrawals": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "withdrawalId", "state", "asset", "amountZat", "maxFeeZat" ], "properties": { "withdrawalId": { "type": "string", "pattern": "^rw_[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "REFERRAL_REQUESTED", "REFERRAL_PREPARING", "REFERRAL_PREPARED", "REFERRAL_SENDING", "REFERRAL_CONFIRMING", "REFERRAL_CONFIRMED", "COMPLETE", "EXPIRED", "MANUAL_REVIEW" ] }, "asset": { "const": "ZEC" }, "amountZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "maxFeeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "feeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "paidZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } }, "pending": { "type": "integer", "minimum": 0 } } } } } }, "404": { "description": "Unknown account/request or invalid key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Withdrawals unavailable.", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "operationId": "requestReferralWithdrawal", "summary": "Reserve earned ZEC for an operator-approved shielded payment", "security": [ { "ReferralKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "Reserved request or identical replay; this response does not mean paid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "withdrawalId", "state", "asset", "amountZat", "maxFeeZat" ], "properties": { "withdrawalId": { "type": "string", "pattern": "^rw_[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "REFERRAL_REQUESTED", "REFERRAL_PREPARING", "REFERRAL_PREPARED", "REFERRAL_SENDING", "REFERRAL_CONFIRMING", "REFERRAL_CONFIRMED", "COMPLETE", "EXPIRED", "MANUAL_REVIEW" ] }, "asset": { "const": "ZEC" }, "amountZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "maxFeeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "feeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "paidZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } }, "400": { "description": "Invalid amount, fee cap or shielded address.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Insufficient credit, another pending request or changed idempotent request.", "content": { "application/json": { "schema": { "type": "object" } } } }, "410": { "description": "Request purged after retention; do not recreate it automatically.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown account/request or invalid key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Withdrawals unavailable.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "description": "Requires explicit client authorization. Save a fresh 32-byte lowercase hex idempotencyKey and the exact body before posting. Retry only that body after an uncertain response; list requests after reload. One pending withdrawal per account. No query parameters or cookies. A separate signed operator approval is required before any wallet send.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "idempotencyKey", "payoutAddress", "amountZat", "maxFeeZat" ], "properties": { "idempotencyKey": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "payoutAddress": { "type": "string", "maxLength": 1024, "description": "Mainnet unified Zcash address with an Ironwood receiver." }, "amountZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Positive exact integer, at most Number.MAX_SAFE_INTEGER minus maxFeeZat." }, "maxFeeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "Maximum network fee debited in addition to the amount, at most 100000 zatoshis." } } } } } } } }, "/api/v1/route/referrals/{code}/withdrawals/{withdrawalId}": { "get": { "operationId": "getReferralWithdrawal", "summary": "Read withdrawal status", "security": [ { "ReferralKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } }, { "name": "withdrawalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rw_[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "COMPLETE requires confirmed matching recipient evidence.", "content": { "application/json": { "schema": { "type": "object", "required": [ "withdrawalId", "state", "asset", "amountZat", "maxFeeZat" ], "properties": { "withdrawalId": { "type": "string", "pattern": "^rw_[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "REFERRAL_REQUESTED", "REFERRAL_PREPARING", "REFERRAL_PREPARED", "REFERRAL_SENDING", "REFERRAL_CONFIRMING", "REFERRAL_CONFIRMED", "COMPLETE", "EXPIRED", "MANUAL_REVIEW" ] }, "asset": { "const": "ZEC" }, "amountZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "maxFeeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "feeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "paidZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } }, "410": { "description": "Status purged after 72 hours; aggregate balance remains.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown account/request or invalid key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Withdrawals unavailable.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/v1/route/referrals/{code}/withdrawals/{withdrawalId}/cancel": { "post": { "operationId": "cancelReferralWithdrawal", "summary": "Cancel a request before payment preparation starts", "security": [ { "ReferralKey": [] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^zr_[a-f0-9]{32}$" } }, { "name": "withdrawalId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^rw_[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Cancelled request; held credit released.", "content": { "application/json": { "schema": { "type": "object", "required": [ "withdrawalId", "state", "asset", "amountZat", "maxFeeZat" ], "properties": { "withdrawalId": { "type": "string", "pattern": "^rw_[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "REFERRAL_REQUESTED", "REFERRAL_PREPARING", "REFERRAL_PREPARED", "REFERRAL_SENDING", "REFERRAL_CONFIRMING", "REFERRAL_CONFIRMED", "COMPLETE", "EXPIRED", "MANUAL_REVIEW" ] }, "asset": { "const": "ZEC" }, "amountZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "maxFeeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "feeZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "paidZat": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" } } } } } }, "409": { "description": "Preparation started; automatic cancellation is unavailable.", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown account/request or invalid key.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Withdrawals unavailable.", "content": { "application/json": { "schema": { "type": "object" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {} } } } } } } }, "components": { "schemas": { "Asset": { "type": "object", "required": [ "asset", "network" ], "properties": { "asset": { "type": "string", "examples": [ "BTC", "ETH", "XMR", "ZEC" ] }, "network": { "type": "string", "examples": [ "bitcoin", "ethereum", "monero", "zcash" ] } }, "additionalProperties": false }, "Units": { "type": "string", "pattern": "^[1-9][0-9]{0,99}$", "description": "Positive integer base units; never a decimal or floating-point value." } }, "securitySchemes": { "RouteToken": { "type": "apiKey", "in": "header", "name": "X-Route-Token" }, "ReferralKey": { "type": "apiKey", "in": "header", "name": "X-Referral-Key" } } } }