Submit Order

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.

POST /orders

Submit Order

cURL

curl --request POST \
  --url https://api.tetrafi.io/api/v1/router/orders \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "quoteResponse": {
    "quoteId": "<string>",
    "solverId": "<string>",
    "validUntil": 123,
    "preview": {
      "inputs": [
        {
          "asset": "<string>",
          "amount": "<string>",
          "decimals": 123,
          "symbol": "<string>",
          "priceUsd": 123
        }
      ],
      "outputs": [
        {
          "asset": "<string>",
          "amount": "<string>",
          "minimumAmount": "<string>",
          "decimals": 123,
          "symbol": "<string>",
          "priceUsd": 123,
          "receiver": "<string>"
        }
      ]
    },
    "integrityChecksum": "<string>",
    "order": {
      "type": "<string>",
      "payload": {}
    },
    "eta": 123,
    "routingPath": "<string>",
    "platformFeeBps": 123,
    "lpSpreadBps": 123,
    "composite": {
      "legs": [
        {}
      ],
      "executionModel": "<string>"
    },
    "gas": {
      "native": "<string>",
      "usd": 123
    },
    "warnings": []
  },
  "signature": "<string>",
  "signScheme": "EIP712",
  "permit2Lock": {
    "signature": "<string>",
    "deadline": 123
  },
  "eip3009Authorization": {
    "signature": "<string>",
    "validAfter": 123,
    "validBefore": 123,
    "nonce": "<string>"
  }
}
'

200

{
  "id": "<string>",
  "quoteId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z"
}

Authorizations

X-API-Key · string · header · required

Service-account API key (tfk_test_/tfk_live_).

Headers

Idempotency-Key · string

Client-chosen key that makes retries safe: a repeated POST carrying the same key returns the original order instead of creating a second one.

Body

application/json

quoteResponse · Selected candidate · object · required

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.

Show child attributes

signature · string · required

Hex-encoded EIP-712 signature over the escrow-v0 payload from quote.order (equivalently, the typedData on preflight's orderSignature action).

signScheme · string · default: EIP712

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.

permit2Lock · Permit2Lock · object | null

Permit2 funding lock: one reusable approval of the Permit2 contract, after which each order authorizes its own pull inside the signature.

Show child attributes

eip3009Authorization · Eip3009Authorization · object | null

EIP-3009 funding lock for USDC-style tokens: the transfer is authorized entirely inside the signed message, so no approval transaction ever exists.

Show child attributes

Response

200

application/json

Successful Response

id · string · required

Order identifier - use it for GET /orders/{id} polling and the orders:{id} WebSocket topic.

status · enum<string> · required

State at creation time - normally pending.

Available options: pending, settled, failed

quoteId · string · required

Candidate this order was created from.

createdAt · string<date-time> · required

When the order was accepted.