> ## Documentation Index > Fetch the complete documentation index at: https://tetrafi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Orders > Submit a selected candidate for settlement together with the taker's EIP-712 signature over its escrow-v0 payload. The API checks the signature against the integrity checksum and, on apiSubmit candidates, lands the settlement transaction on-chain and carries the gas; an Idempotency-Key header makes retries safe. ## OpenAPI ```yaml /specs/router-api.json post /orders theme={null} openapi: 3.1.0 info: title: TetraFi Router API version: '1' description: >- Multi-source routing over every eligible execution source. One intent fans out across direct DEX liquidity, the RFQ venue, bridges, issuers, and fiat rails, and comes back as ranked executable candidates - each stating its own guarantees. servers: - url: https://api.tetrafi.io/api/v1/router description: >- Router namespace base URL. The chain is no longer part of the URL - every asset in an intent names its network via chainId. The same host serves the sandbox: authenticate with a tfk_test_ key to route against test corridors, tfk_live_ for production. security: - apiKeyAuth: [] paths: /orders: post: summary: Submit Order description: >- Submit a signed order for settlement. Pass the selected candidate back unchanged together with the taker's EIP-712 signature over its escrow-v0 payload; the API verifies the signature against the integrityChecksum and, on apiSubmit candidates, lands the settlement transaction on-chain and carries the gas. Send an Idempotency-Key header (the quoteId works well) so a retried POST can never double-submit. operationId: submitOrder parameters: - name: Idempotency-Key in: header required: false schema: type: string title: Idempotency Key description: >- Client-chosen key that makes retries safe: a repeated POST carrying the same key returns the original order instead of creating a second one. requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderSubmitRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Order' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: OrderSubmitRequest: properties: quoteResponse: $ref: '#/components/schemas/QuoteCandidate' title: Selected candidate description: >- The candidate you picked, passed back exactly as it appeared in the quotes response. The integrityChecksum binds the submission to those terms; any mutation is rejected. signature: type: string title: Signature description: >- Hex-encoded EIP-712 signature over the escrow-v0 payload from quote.order (equivalently, the typedData on preflight's orderSignature action). signScheme: type: string title: Sign Scheme description: >- How the signature verifies: EIP712 for standard ECDSA from an EOA (the default), or EIP1271 for smart-contract wallets that validate via isValidSignature on-chain. default: EIP712 permit2Lock: anyOf: - $ref: '#/components/schemas/Permit2Lock' - type: 'null' title: Permit2 lock description: >- Inline Permit2 material - include only when the preflight plan asked for it; a standing Permit2 grant makes this unnecessary. eip3009Authorization: anyOf: - $ref: '#/components/schemas/Eip3009Authorization' - type: 'null' title: EIP-3009 authorization description: >- Signed transfer authorization for EIP-3009 tokens (USDC-style) when preflight selected that lock. Resource-lock candidates need no inline material - the balance is already deposited. type: object required: - quoteResponse - signature title: OrderSubmitRequest GasEstimate: properties: native: type: string title: Native description: >- Estimated gas cost in the execution chain's native currency, base units. Zero on apiSubmit candidates, where TetraFi carries the gas. usd: anyOf: - type: number - type: 'null' title: Usd description: The same estimate in US dollars, when a price is available. type: object required: - native title: GasEstimate HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError OrderStatus: type: string enum: - pending - settled - failed title: OrderStatus description: >- Order lifecycle state. pending - accepted and progressing; settled - delivery proven and funds released (terminal); failed - could not settle before expiry, the escrowed input follows the refund path (terminal). The same transitions are pushed over WebSocket as order.created, order.settled, and order.failed on the orders:{id} topic. Order: properties: id: type: string title: Id description: >- Order identifier - use it for GET /orders/{id} polling and the orders:{id} WebSocket topic. status: $ref: '#/components/schemas/OrderStatus' description: State at creation time - normally pending. quoteId: type: string title: Quoteid description: Candidate this order was created from. createdAt: type: string format: date-time title: Createdat description: When the order was accepted. type: object required: - id - status - quoteId - createdAt title: Order StandardOrder: properties: type: type: string title: Type description: Order payload type; escrow-v0 for the current settlement contract. payload: type: object title: Payload description: >- Complete EIP-712 envelope - domain, types, and the StandardOrder message - delivered verbatim by the API. Treat it as opaque: sign exactly what arrives in quote.order (or the typedData on preflight's orderSignature action) and never assemble or edit it locally. The signed terms cover the parties, the inputs you escrow, the minimum outputs that must be delivered, an expiry after which the unfilled order refunds, and a domain-scoped nonce; they are bound to your submission by the integrityChecksum. type: object required: - type - payload title: StandardOrder description: >- The escrow-v0 order payload a candidate asks you to sign. Anything you would want different - receiver, amounts, expiry - changes at quote time, not signing time. Permit2Lock: properties: signature: type: string title: Signature description: Signed Permit2 permit authorizing the escrow to pull the input token. deadline: type: integer title: Deadline description: Unix timestamp after which the permit is void. type: object required: - signature - deadline title: Permit2Lock description: >- Permit2 funding lock: one reusable approval of the Permit2 contract, after which each order authorizes its own pull inside the signature. Eip3009Authorization: properties: signature: type: string title: Signature description: Signed transferWithAuthorization message. validAfter: type: integer title: Valid After description: Unix timestamp from which the authorization becomes usable. validBefore: type: integer title: Valid Before description: Unix timestamp at which the authorization expires. nonce: type: string title: Nonce description: Random 32-byte nonce making the authorization single-use. type: object required: - signature - validAfter - validBefore - nonce title: Eip3009Authorization description: >- EIP-3009 funding lock for USDC-style tokens: the transfer is authorized entirely inside the signed message, so no approval transaction ever exists. PriceWarning: properties: code: type: integer title: Code description: Numeric warning identifier. message: type: string title: Message description: What the warning flags - unusual pricing, thin liquidity, or similar. type: object required: - code - message title: PriceWarning description: >- Non-blocking warning attached to a candidate's warnings array so unusual conditions surface before you select it. PreviewOutput: properties: asset: type: string title: Asset description: >- Delivered asset in CAIP-19 form, e.g. eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. amount: type: string title: Amount description: Base-unit amount delivered if the candidate executes exactly as quoted. minimumAmount: anyOf: - type: string - type: 'null' title: Minimumamount description: >- Floor the settlement must deliver - the per-candidate guarantee that replaces a request-level slippage parameter. decimals: anyOf: - type: integer - type: 'null' title: Decimals description: Token decimals, for converting base units to a display amount. symbol: anyOf: - type: string - type: 'null' title: Symbol description: Token ticker symbol. priceUsd: anyOf: - type: number - type: 'null' title: Priceusd description: Reference US-dollar price per whole token, when available. receiver: anyOf: - type: string - type: 'null' title: Receiver description: Wallet this output is delivered to. type: object required: - asset - amount title: PreviewOutput PreviewInput: properties: asset: type: string title: Asset description: >- Escrowed asset in CAIP-19 form, e.g. eip155:10/erc20:0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85. amount: type: string title: Amount description: Base-unit amount the user sends. decimals: anyOf: - type: integer - type: 'null' title: Decimals description: Token decimals, for converting base units to a display amount. symbol: anyOf: - type: string - type: 'null' title: Symbol description: Token ticker symbol. priceUsd: anyOf: - type: number - type: 'null' title: Priceusd description: Reference US-dollar price per whole token, when available. type: object required: - asset - amount title: PreviewInput QuoteCandidate: properties: quoteId: type: string title: Quoteid description: Identifier that follows the candidate through preflight, submission, and status. solverId: type: string title: Solverid description: >- Source that produced the candidate - e.g. tetrafi-native, a DEX adapter, or a bridge route. executionMode: type: string enum: - apiSubmit - walletBroadcast title: Executionmode description: >- Who lands the transaction on-chain: apiSubmit means TetraFi submits the settlement after you sign; walletBroadcast means you broadcast a prepared transaction yourself. This per-candidate property replaces a request-level sponsored-gas flag. order: anyOf: - $ref: '#/components/schemas/StandardOrder' - type: 'null' description: >- The escrow-v0 payload to sign, present on direct candidates. Composite planner routes carry prepared transactions via preflight instead. validUntil: type: integer title: Validuntil description: Unix timestamp ending the firmness window; the candidate expires at this moment. eta: anyOf: - type: integer - type: 'null' title: Eta description: Expected seconds until settlement. preview: type: object title: Preview description: >- Human-readable ins and outs - what the user sends and what arrives if the candidate executes as quoted. properties: inputs: items: $ref: '#/components/schemas/PreviewInput' type: array title: Inputs outputs: items: $ref: '#/components/schemas/PreviewOutput' type: array title: Outputs required: - inputs - outputs integrityChecksum: type: string title: Integritychecksum description: >- Tamper-evidence binding the terms you were shown to the terms you submit; any drift between them is rejected. routingPath: type: string title: Routingpath description: >- Route shape - direct for a single-source fill; multi-leg routes describe their legs in composite. platformFeeBps: anyOf: - type: integer - type: 'null' title: Platformfeebps description: >- Platform fee applied to this candidate, in basis points. Monetization is configured per workspace, not passed per request. lpSpreadBps: anyOf: - type: integer - type: 'null' title: Lpspreadbps description: Spread earned by the liquidity provider on this candidate, in basis points. composite: anyOf: - type: object properties: legs: type: array items: type: object title: Legs description: Ordered legs of the planner route, each naming its kind and chain. executionModel: type: string title: Executionmodel description: How the legs run, e.g. sequential. - type: 'null' title: Composite description: >- Present on planner-assembled multi-leg routes; absent on direct single-source quotes. gas: anyOf: - $ref: '#/components/schemas/GasEstimate' - type: 'null' description: >- Gas context for the candidate; the ranking already compares candidates net of gas and explicit fees. warnings: items: $ref: '#/components/schemas/PriceWarning' type: array title: Warnings description: Non-blocking warnings attached to the candidate. default: [] type: object required: - quoteId - solverId - executionMode - validUntil - preview - integrityChecksum title: QuoteCandidate ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: Service-account API key (tfk_test_/tfk_live_). ``` ## OpenAPI ````yaml POST /orders openapi: 3.1.0 info: title: TetraFi RFQ API version: '1' description: >- Firm, escrow-backed quotes from competing solvers and LPs. Every quote is a signed commitment priced from the counterparty's own inventory - executable exactly as returned, with no re-pricing and no last look - and every order settles through a delivery-or-refund escrow: the output is delivered or the input comes back, never limbo. servers: - url: https://api.tetrafi.io/api/v1/rfq description: >- RFQ namespace base URL. The chain is no longer part of the URL - every asset in an intent names its network via chainId. The same host serves the sandbox: authenticate with a tfk_test_ key to quote against test corridors, tfk_live_ for production. security: - apiKeyAuth: [] paths: /orders: post: summary: Submit Order description: >- Places an order against a firm quote collected from `POST /quotes`. Send the chosen candidate back untouched as `quoteResponse`, together with the taker's signature over its escrow-v0 payload; the API checks the signature against the integrityChecksum and - on apiSubmit quotes - lands the settlement transaction on-chain itself. Gas on that path is carried by TetraFi and already reflected in the quoted price. `signScheme` defaults to EIP712 for standard EOA signatures; smart-contract wallets pass EIP1271 and are verified via isValidSignature on-chain. Always send an Idempotency-Key header (the quoteId is a natural choice): a retried POST can then never double-submit. operationId: submitOrder parameters: - name: Idempotency-Key in: header required: false schema: type: string title: Idempotency Key description: >- Client-chosen key that makes retries safe: a repeated POST carrying the same key returns the original order instead of creating a second one. requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderSubmitRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Order' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: OrderSubmitRequest: properties: quoteResponse: $ref: '#/components/schemas/QuoteCandidate' title: Selected quote description: >- The firm quote you picked, passed back exactly as it appeared in the quotes response. The integrityChecksum binds your submission to those terms; any mutation is rejected. signature: type: string title: Signature description: >- Hex-encoded EIP-712 signature over the escrow-v0 payload from quote.order (equivalently, the typedData on preflight's orderSignature action). signScheme: type: string title: Sign Scheme description: >- How the signature verifies: EIP712 for standard ECDSA from an EOA (the default), or EIP1271 for smart-contract wallets validated through isValidSignature on-chain. default: EIP712 permit2Lock: anyOf: - $ref: '#/components/schemas/Permit2Lock' - type: 'null' title: Permit2 lock description: >- Inline Permit2 material - include it only when the preflight plan asked for it; a standing Permit2 grant makes this unnecessary. eip3009Authorization: anyOf: - $ref: '#/components/schemas/Eip3009Authorization' - type: 'null' title: EIP-3009 authorization description: >- Signed transfer authorization for EIP-3009 tokens (USDC-style) when preflight selected that lock. Resource-lock quotes need no inline material - the balance is already deposited. type: object required: - quoteResponse - signature title: OrderSubmitRequest Order: properties: id: type: string title: Id description: >- Order identifier - poll GET /orders/{id} with it or subscribe to the orders:{id} WebSocket topic. status: $ref: '#/components/schemas/OrderStatus' description: State at acceptance time - normally pending. quoteId: type: string title: Quoteid description: The firm quote this order executes. createdAt: type: string format: date-time title: Createdat description: When the API accepted the submission. type: object required: - id - status - quoteId - createdAt title: Order examples: - id: ord_01J2M9C1D3F5H7K9M1P3R5T7V9 status: pending quoteId: q_01J2M8W3N9RQK5T7V1X4Z6B8D0 createdAt: '2026-07-20T14:02:11Z' HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError QuoteCandidate: properties: quoteId: type: string title: Quoteid description: >- Identifier that follows this quote through preflight, submission, and status tracking. solverId: type: string title: Solverid description: >- The LP or solver standing behind the commitment - a roster id from GET /solvers. executionMode: type: string enum: - apiSubmit - walletBroadcast title: Executionmode description: >- Who puts the settlement on-chain: apiSubmit - TetraFi submits after you sign and carries the gas; walletBroadcast - you broadcast the prepared transaction from your own RPC. This is a per-quote property; there is no request-level gasless flag. order: anyOf: - $ref: '#/components/schemas/StandardOrder' - type: 'null' description: >- The escrow-v0 payload to sign, exactly as returned. Null only when the quote's signable material is delivered through preflight instead. validUntil: type: integer title: Validuntil description: >- Unix second the firmness window closes; the quote expires at this moment - sign and submit before it. eta: anyOf: - type: integer - type: 'null' title: Eta description: Expected seconds from submission to settlement. validity: anyOf: - $ref: '#/components/schemas/ValidityWindow' - type: 'null' description: >- Structured firmness window - validUntil restated together with the request's minValidUntil floor, for integrations that track expiries explicitly. preview: type: object title: Preview description: >- Human-readable trade terms - what the taker escrows and what the escrow enforces on delivery. properties: inputs: items: $ref: '#/components/schemas/PreviewInput' type: array title: Inputs outputs: items: $ref: '#/components/schemas/PreviewOutput' type: array title: Outputs required: - inputs - outputs integrityChecksum: type: string title: Integritychecksum description: >- Tamper-evidence binding the terms you were shown to the terms you submit; any drift between the two is rejected as an integrity failure. routingPath: type: string title: Routingpath description: >- Always direct on RFQ quotes - a single escrow fill with no planner legs. Split fills remain direct and are described in splitFill. platformFeeBps: anyOf: - type: integer - type: 'null' title: Platformfeebps description: >- Platform fee applied to this quote, in basis points. Monetization is configured on the workspace, not passed per request. lpSpreadBps: anyOf: - type: integer - type: 'null' title: Lpspreadbps description: Spread the quoting LP earns on this trade, in basis points. splitFill: anyOf: - $ref: '#/components/schemas/SplitFillDetail' - type: 'null' title: Splitfill description: >- Populated when several LPs jointly fill the size inside one order; null on single-counterparty quotes. Either way there is one payload, one signature, one guarantee. gas: anyOf: - $ref: '#/components/schemas/GasEstimate' - type: 'null' description: >- Gas context for the quote; zero-native on apiSubmit, where TetraFi carries the cost. warnings: items: $ref: '#/components/schemas/PriceWarning' type: array title: Warnings description: Non-blocking warnings attached to the quote. default: [] type: object required: - quoteId - solverId - executionMode - validUntil - preview - integrityChecksum title: QuoteCandidate description: >- One firm, escrow-backed quote from a competing solver or LP. Settlement and approval contract addresses are deliberately absent here - preflight's nextActions carry the exact contracts for the quote you pick, so integrations never hardcode them. Permit2Lock: properties: signature: type: string title: Signature description: >- Signed Permit2 permit authorizing the escrow to pull the input token. deadline: type: integer title: Deadline description: Unix timestamp after which the permit is void. type: object required: - signature - deadline title: Permit2Lock description: >- Permit2 funding lock: one reusable approval of the Permit2 contract, after which every order authorizes its own pull inside the signature. Eip3009Authorization: properties: signature: type: string title: Signature description: Signed transferWithAuthorization message. validAfter: type: integer title: Valid After description: Unix timestamp from which the authorization becomes usable. validBefore: type: integer title: Valid Before description: Unix timestamp at which the authorization expires. nonce: type: string title: Nonce description: Random 32-byte nonce making the authorization single-use. type: object required: - signature - validAfter - validBefore - nonce title: Eip3009Authorization description: >- EIP-3009 funding lock for USDC-style tokens: the transfer is authorized entirely inside the signed message, so no approval transaction ever exists. OrderStatus: type: string enum: - pending - settled - failed title: OrderStatus description: >- Order lifecycle state, lowercase. pending - accepted and progressing; settled - delivery proven and funds released (terminal); failed - the order could not settle inside its window, so the escrowed input follows the refund path (terminal, never lost funds). Each transition is also pushed over WebSocket as order.created, order.settled, or order.failed on the orders:{id} topic. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError StandardOrder: properties: type: type: string title: Type description: Order payload type; escrow-v0 for the current settlement contract. payload: type: object title: Payload description: >- Complete EIP-712 envelope - domain, types, and the StandardOrder message - delivered verbatim by the API. Treat it as opaque: sign exactly what arrives in quote.order (or the typedData on preflight's orderSignature action) and never assemble or edit it locally. The signed terms name the parties, the inputs you escrow, the minimum outputs that must be delivered, an expiry after which the unfilled order refunds, and a domain-scoped nonce; the integrityChecksum binds them to your submission. type: object required: - type - payload title: StandardOrder description: >- The escrow-v0 order payload a firm quote asks you to sign. One envelope covers single-counterparty and split fills alike - one signature either way. Anything you would want different (receiver, amounts, expiry) changes at quote time, never at signing time. ValidityWindow: properties: validUntil: type: integer title: Valid Until description: >- Unix second at which the quote stops being executable - sign and submit before it. minValidUntil: anyOf: - type: integer - type: 'null' title: Min Valid Until description: >- Floor the request asked for via minValidUntil; quotes expiring sooner were filtered out before ranking. Null when the request set no floor. type: object required: - validUntil title: ValidityWindow description: >- Firmness window of a quote - the span in which it is executable exactly as signed. This replaces the older fixed expiry tiers: each quote states its own window, and integrations that need more runway raise the floor per request instead of choosing a tier. PreviewInput: properties: asset: type: string title: Asset description: >- Escrowed asset in CAIP-19 form, e.g. eip155:10/erc20:0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85. amount: type: string title: Amount description: Base-unit amount the taker escrows. decimals: anyOf: - type: integer - type: 'null' title: Decimals description: Token decimals, for converting base units to a display amount. symbol: anyOf: - type: string - type: 'null' title: Symbol description: Token ticker symbol. priceUsd: anyOf: - type: number - type: 'null' title: Priceusd description: Reference US-dollar price per whole token, when available. type: object required: - asset - amount title: PreviewInput PreviewOutput: properties: asset: type: string title: Asset description: >- Delivered asset in CAIP-19 form, e.g. eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913. amount: type: string title: Amount description: Base-unit delivery if the order settles exactly as quoted. minimumAmount: anyOf: - type: string - type: 'null' title: Minimumamount description: >- Floor the escrow enforces on delivery. On firm RFQ quotes this equals amount - the quote is the commitment, which is why no slippage parameter exists. decimals: anyOf: - type: integer - type: 'null' title: Decimals description: Token decimals, for converting base units to a display amount. symbol: anyOf: - type: string - type: 'null' title: Symbol description: Token ticker symbol. priceUsd: anyOf: - type: number - type: 'null' title: Priceusd description: Reference US-dollar price per whole token, when available. receiver: anyOf: - type: string - type: 'null' title: Receiver description: Wallet this output is delivered to. amountBeforeFees: anyOf: - type: string - type: 'null' title: Amountbeforefees description: >- Delivery before the platform fee and LP spread are taken, for fee transparency. deltaFromMid: anyOf: - type: number - type: 'null' title: Deltafrommid description: >- Relative distance of the quoted price from a reference mid; negative means worse than mid. Useful for best-execution checks across competing quotes. type: object required: - asset - amount title: PreviewOutput SplitFillDetail: properties: fills: items: type: object title: SplitFillSlice properties: solverId: type: string title: Solverid description: LP taking this slice of the order. portionBps: type: integer title: Portionbps description: >- Slice of the total input covered by this LP, in basis points of the order size. outputAmount: type: string title: Outputamount description: Base-unit output this slice delivers. required: - solverId - portionBps type: array title: Fills description: Ordered slices, one per participating LP. executionModel: type: string title: Executionmodel description: >- How the slices settle - atomic: every slice delivers inside the same escrow order or the whole order refunds. type: object required: - fills title: SplitFillDetail description: >- Breakdown present when several LPs jointly fill one order. The taker experience does not change: a single escrow-v0 payload, a single signature, and one delivery-or-refund guarantee covering every slice. GasEstimate: properties: native: type: string title: Native description: >- Estimated gas cost in the settlement chain's native currency, base units. Zero on apiSubmit quotes, where TetraFi carries the gas. usd: anyOf: - type: number - type: 'null' title: Usd description: The same estimate in US dollars, when a price is available. type: object required: - native title: GasEstimate PriceWarning: properties: code: type: integer title: Code description: Numeric warning identifier. message: type: string title: Message description: >- What the warning flags - unusual pricing, thin corridor inventory, or similar. type: object required: - code - message title: PriceWarning description: >- Non-blocking warning attached to a quote's warnings array so unusual conditions surface before you select it. securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: Service-account API key (tfk_test_/tfk_live_). ````