Orders API¶

Use this page if you can't use the SDK, or you want to control every step. The SDK makes exactly these calls.

All order routes live under https://api.tao.com/orders/v2. Success responses use HAL (application/hal+json, camelCase), and errors use RFC 9457 problem details (application/problem+json). Every call needs the wallet-bound Bearer token described in Authentication:

Authorization: Bearer <access_token>

Flow¶

POST /orders/v2/order-intents authors the order. It is a dry run.
Your wallet signs the returned instruction.
POST /orders/v2/orders registers the signed order and opens it.
GET /orders/v2/orders/{id} follows it until it is FILLED, FAILED, or CANCELLED.

Author an order¶

POST /orders/v2/order-intents returns the unsigned instruction for a swap and opens nothing.

POST /orders/v2/order-intents
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "source": {
    "currency": "urn:bittensor:mainnet:native",
    "amount": "1000000000"
  },
  "destination": {
    "currency": "urn:bittensor:mainnet:alpha:18",
    "address": "<validator hotkey, SS58>",
    "limitPrice": 0.01
  },
  "signerAddress": "<coldkey, SS58>"
}

To ask for what the user receives instead, set destination.amount and leave out source.amount. This request solves for the TAO needed to receive 10 alpha of subnet 18:

{
  "source": {
    "currency": "urn:bittensor:mainnet:native"
  },
  "destination": {
    "currency": "urn:bittensor:mainnet:alpha:18",
    "amount": "10000000000",
    "address": "<validator hotkey, SS58>",
    "limitPrice": 0.01
  },
  "signerAddress": "<coldkey, SS58>"
}

Field	Description
`source.currency`, `destination.currency`	Asset URNs: `urn:bittensor:<network>:native` for TAO and `urn:bittensor:<network>:alpha:<netuid>` for subnet alpha (netuid `0` is Root).
`source.amount`, `destination.amount`	Integer amount in rao, as a digit string. Set exactly one. `source.amount` spends that much. `destination.amount` asks the service to solve for the smallest source amount that pays out at least that much after every fee, and the authored `order` carries both amounts.
`address`	The validator hotkey (SS58). Required on every alpha leg.
`limitPrice`	The maximum slippage against the current subnet price, as a number from 0 to 1 (`0.05` = 5%). Required on one leg for some swaps. See slippage limits.
`signerAddress`	The wallet's SS58 address. Must equal the token's `username`.

The response has status 200. The X-Provenance-Token header carries the single-use provenance token you need to register the order.

{
  "_links": {
    "instruction": { "href": "https://api.tao.com/orders/v2/orders" }
  },
  "order": {
    "type": "tao_to_alpha",
    "source": { "currency": "urn:bittensor:mainnet:native", "amount": "1000000000" },
    "destination": {
      "currency": "urn:bittensor:mainnet:alpha:18",
      "address": "<validator hotkey, SS58>",
      "limitPrice": 0.01
    },
    "signerAddress": "<coldkey, SS58>"
  },
  "instruction": {
    "type": "SUBSTRATE_EXTRINSIC",
    "payload": { "...": "Polkadot-API TxPayloadV1 JSON" }
  },
  "estimatedFees": [
    {
      "feeType": "TRANSACTION",
      "userPayable": true,
      "amount": [
        { "currency": "urn:bittensor:mainnet:native", "value": "900000" },
        { "currency": "USD", "value": "0.31" }
      ]
    }
  ],
  "quotes": [
    {
      "amount": [
        { "currency": "urn:bittensor:mainnet:alpha:18", "value": "..." },
        { "currency": "USD", "value": "..." }
      ],
      "fees": []
    }
  ],
  "warnings": []
}

Field	Description
`order`	The order envelope. Send it back unchanged when you register. `order.type` is the order type the service chose.
`instruction`	What the wallet signs. `SUBSTRATE_EXTRINSIC` has a Polkadot-API `TxPayloadV1` JSON `payload`. `RAW` has a hex `payload`.
`_links.instruction.href`	Where to post the signed order.
`estimatedFees`	The fee estimates. Each lists its amount in its own currency first, a TAO conversion when it has one, and USD last. `userPayable: false` marks fees the user does not pay. `feeType` is `TRANSACTION`, `PLATFORM`, `SUBNET_AMM`, or `MEV_SHIELD`.
`quotes`	What the user receives after every fee, in the destination currency, in native TAO when that differs, and in USD last. It is an estimate from the pool as the service sees it now. For a `destination.amount` order it is reversed: what the user pays, every fee added, in the source currency first.
`warnings`	Failed pre-flight checks, each with a `code` and, for some codes, `minimumAmount` or `maximumAmount`. Empty when the order passes. Do not sign an order with warnings: registering it is rejected with `preflight-failed`, whose `errors` repeat the same `code` values with a `detail` message added. See pre-flight checks.

The instruction is built from the wallet's current nonce and chain state. Submit it promptly, and author again if anything changed.

Sign the instruction¶

Sign the instruction with the user's wallet, exactly as authored.

SUBSTRATE_EXTRINSIC: build the signed extrinsic from payload with an immortal era, and with the call data and extensions untouched. The signed value is the full extrinsic as 0x-prefixed hex.
RAW: sign the payload bytes. The signed value is the signature as 0x-prefixed hex.

Only sr25519 and ed25519 signatures are accepted.

Register the order¶

POST /orders/v2/orders opens the signed order. Send the order exactly as authored, the provenance token, and a unique idempotency key.

POST /orders/v2/orders
Content-Type: application/json
Authorization: Bearer <access_token>
Idempotency-Key: <unique key>
X-Provenance-Token: <token from the author response>

{
  "order": { "...": "the order from the author response" },
  "signedInstruction": {
    "type": "sr25519",
    "value": "0x..."
  }
}

Header or field	Description
`Idempotency-Key`	A unique key per order. Retrying with the same key and the same order returns the same order. The same key with a different order answers `409`.
`X-Provenance-Token`	The single-use token from the author response. A token that does not match the order, or was already used, answers `403`.
`signedInstruction.type`	`sr25519` or `ed25519`.

The response has status 201 and contains the order with status OPEN. Read the order ID from the last segment of _links.self.href.

Get an order¶

GET /orders/v2/orders/{id} returns one of your orders.

Field	Description
`type`, `status`	The order type and its status.
`source`, `destination`, `signerAddress`	The order as registered.
`events`	Lifecycle events with `type`, `at`, and, when relevant, `transactionHash` and `failureReason`.
`items`	Once filled: what was bought, sold, and charged. Each item has an `amount`, an `itemKind` of `BUY`, `SELL`, or `FEE`, an optional `feeType`, and an optional `secondaryAmount`. Amounts are `{ "value", "currency" }`.
`createdAt`, `updatedAt`	Timestamps.
`_links.self`, `_links.cancel`	Links to the order. `cancel` is present while you can cancel it.

An order you did not place, or that does not exist, answers 404.

List orders¶

GET /orders/v2/orders returns your orders, a page at a time.

Query parameter	Description
`status`	`OPEN`, `SUBMITTED`, `FILLED`, `FAILED`, or `CANCELLED`.
`orderType`	An order type, such as `tao_to_alpha`.
`orderCategory`	The order category. Use `BITTENSOR_MARKET` for market orders.
`limit`	The page size, 1 to 100.
`cursor`	The cursor from the previous page's `next` link.

Orders are in _embedded.order, and _links.next and _links.prev carry the cursor for the neighboring pages. An unknown query parameter answers 422.

Cancel an order¶

POST /orders/v2/orders/{id}/cancel cancels an order. It is allowed only while the order is OPEN. Otherwise it answers 409 with cancel-not-allowed.

Order status¶

An order's status is the last thing the executor reported.

Status	Meaning
`OPEN`	Registered and waiting to be executed. You can cancel.
`CLAIMED`	Execution has picked the order up.
`SUBMITTED`	The transaction was sent to the network.
`ACCEPTED`	The network accepted the transaction. It is not final until `FILLED`.
`FILLED`	Executed on chain.
`FAILED`	The order did not execute. The event's `failureReason` says why.
`ERROR`	An error was reported with the order. It is not a final status. See the event's `failureReason`.
`CANCELLED`	You cancelled it while it was `OPEN`.

FILLED, FAILED, and CANCELLED are final. ERROR is not: if you poll for an order, stop at a final status, set a timeout, and show the event's failureReason when you see ERROR.

Errors¶

Errors are RFC 9457 problem details with type, title, status, detail, and, when relevant, field, errors, and requestId. The error code is the last segment of type.

Code	Status	Meaning
`invalid-request`	422 (400 for an unreadable body)	A field is wrong or missing, including a required `limitPrice`. `field` names it.
`invalid-address`	422	An address is not valid SS58.
`unsupported-swap`, `same-asset`	422	The pair is not supported.
`invalid-provenance`	403	The provenance token does not match the order, or was already used. Author again.
`preflight-failed`	422	The order failed a pre-flight check when it was registered. `errors` lists the failed checks: the same entries as the author response's `warnings` (`code`, and `minimumAmount` or `maximumAmount` when present), each with a `detail` message added. Nothing was submitted.
`invalid-signature`	422	The signature does not verify, or the call or era differs from what was authored.
`forbidden`	403	The token's `username` is not the order's `signerAddress`.
`idempotency-conflict`	409	The idempotency key was used with a different order.
`order-not-found`	404	No such order for this wallet.
`cancel-not-allowed`	409	The order is no longer `OPEN`.
`chain-unavailable`, `store-unavailable`	503	A dependency is down. Retry later.
`internal-error`	500	Unexpected. Report the `requestId`.

A request with a missing, invalid, or expired token is rejected at the API gateway before it reaches the service, and the response is not a problem document.