Orders

Submit, view, and cancel orders on Turbine.

Submit Order

Create a new order on the orderbook.

POST /api/v1/orders

Request Body

{
  "order": {
    "marketId": "0x1234...abcd",
    "trader": "0xYourAddress...",
    "side": 0,
    "outcome": 0,
    "price": 500000,
    "size": 10000000,
    "nonce": 1234567890,
    "expiration": 1735689600,
    "makerFeeRecipient": "0x0000000000000000000000000000000000000000"
  },
  "signature": "0x...",
  "permitSignature": {
    "nonce": 0,
    "value": "100000000",
    "deadline": 1735689600,
    "v": 27,
    "r": "0x...",
    "s": "0x..."
  }
}

Order Fields

Permit Signature (Optional)

For per-order gasless USDC approval. Include when buying without prior USDC approval.

**Recommended alternative:** Use a one-time max permit via `POST /api/v1/relayer/usdc-permit` instead. This approves USDC once, and all future orders can omit `permitSignature`.

Response

{
  "orderHash": "0xabc123...",
  "status": "accepted",
  "matches": 2,
  "timestamp": 1735689000
}

Validation Rules

• Price: Must be between 1 and 999999 (exclusive of 0 and 1000000)
• Size: Must be greater than 0
• Expiration: Must be at least 60 seconds in the future
• Signature: Must be a valid EIP-712 typed data signature (65 bytes)

EIP-712 Signing

Orders must be signed using EIP-712 typed data:

const domain = {
  name: "Turbine Settlement",
  version: "1",
  chainId: 137,
  verifyingContract: "0xSettlementAddress..."
};

const types = {
  Order: [
    { name: "marketId", type: "bytes32" },
    { name: "trader", type: "address" },
    { name: "side", type: "uint8" },
    { name: "outcome", type: "uint8" },
    { name: "price", type: "uint64" },
    { name: "size", type: "uint64" },
    { name: "nonce", type: "uint64" },
    { name: "expiration", type: "uint64" },
    { name: "makerFeeRecipient", type: "address" }
  ]
};

const signature = await wallet._signTypedData(domain, types, order);

Example

curl -X POST https://api.turbinefi.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "marketId": "0x...",
      "trader": "0x...",
      "side": 0,
      "outcome": 0,
      "price": 500000,
      "size": 10000000,
      "nonce": 1234567890,
      "expiration": 1735689600,
      "makerFeeRecipient": "0x0000000000000000000000000000000000000000"
    },
    "signature": "0x..."
  }'

Get User Orders

Retrieve open orders for a user.

GET /api/v1/orders

Query Parameters

Response

Example

curl "https://api.turbinefi.com/api/v1/orders?trader=0xYourAddress"

Cancel Order

Cancel an open order.

DELETE /api/v1/orders/{hash}

Path Parameters

Query Parameters

Response

{
  "status": "cancelled",
  "orderHash": "0xabc..."
}

Example

curl -X DELETE "https://api.turbinefi.com/api/v1/orders/0xabc...?marketId=0x...&side=buy"

Get All User Orders

Returns all open orders for a user across all markets on a specific chain.

GET /api/v1/users/{address}/orders

Path Parameters

Query Parameters

Example

curl "https://api.turbinefi.com/api/v1/users/0xYourAddress/orders?chain_id=137"

Failed Trades

Returns trades that failed settlement in the last 24 hours.

GET /api/v1/failed-trades

Pending Trades

Returns trades waiting for blockchain confirmation.

GET /api/v1/pending-trades

Settlement Status

Look up the status of a specific settlement transaction.

GET /api/v1/settlements/{txHash}

Path Parameters

If the transaction is not found, `found` will be false and all other fields will be omitted.

Matching Behavior

• Price-time priority: Orders match against the best available price first.
• Same outcome only: BUY YES matches SELL YES, never SELL NO.
• Partial fills: Orders can partially fill; the remaining size stays on the book.
• Blockchain settlement: Matched trades are submitted to the blockchain for on-chain settlement.

The matches field in the submit response indicates how many counter-orders were matched.