---
title: "Buy a size split across both legs of an approved cross-venue market link"
method: POST
path: "/orders/route-buy"
tags: ["Routing"]
---

# Buy a size split across both legs of an approved cross-venue market link

`POST /orders/route-buy`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/orders/route-buy`
- Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

Executes the plan `GET /orders/route-quote` previews: creates a parent route row and submits one child order per leg. Children go through the same validation, admission and rate limiting as `POST /orders`.
**Partial success is a `200`.** `status` is always `submitting`; a leg that failed to submit has `order_id: null` and a populated `legs[].error`. Track the parent via `GET /orders/routes` and the children via `GET /orders/{order_id}`.
**Feature-gated.** Disabled unless `ROUTED_EXECUTION_ENABLED` is set on the deployment; otherwise every call is a `403`.
**Auth & scope.** Requires the mutation gate (API-key triple satisfies it). This handler enforces no scope of its own — each child order carries the normal `trade:execute` and per-provider checks.

## Request body

- OrderRouteBuyRequest: Body for `POST /orders/route-buy`.
  - `provider` string, required
  - `market_id` string, required
  - `side` 'yes' | 'no', nullable: `yes` or `no`. Supply this or `outcome`.
  - `outcome` string, nullable: Venue-native outcome label, as an alternative to `side`.
  - `quantity` string, required: Decimal string, must be > 0.
  - `slippage_cents` integer, nullable: Must be in `[1, 99]` if provided.

## Response `200`

Route created and children dispatched. Inspect `legs[].error` for per-leg failures.

- OrderRouteBuyResponse: Response for `POST /orders/route-buy`. Individual legs can fail while the request succeeds — always inspect `legs[].error`.
  - `route_order_id` string, uuid, required
  - `status` 'submitting', required: Always `submitting` — children are dispatched asynchronously. Poll `GET /orders/routes`.
  - `requested` string, required
  - `planned` string, required
  - `legs` OrderRouteBuyLegResult[], required
    - `provider` string, required
    - `order_id` string, uuid, nullable: Null when this leg failed to submit — see `error`.
    - `planned_qty` string, required
    - `planned_limit_price` string, required
    - `error` string, nullable: Per-leg submission failure, reported at HTTP 200. An opaque debug rendering of the underlying order error — do not parse it.
  - `notes` string[], required

## Other responses

- `400`: `slippage_cents` outside `[1, 99]`, non-positive `quantity`, an unresolvable `side`/`outcome`, or a malformed authenticated user id. Empty body (status code only).
- `401`: No valid credential presented — missing/invalid API-key headers or an invalid/expired session token.
- `403`: Routed execution is disabled on this deployment. Empty body (status code only).
- `422`: No approved market link for this market or no routable sources (empty body), or the planner produced no legs — then `{"error":"nothing_planned","stop":...,"notes":[...]}`, where `stop` carries the quote's stop names and `below_minimum` means the notes name each venue leg excluded for its minimum order.
- `500`: The parent route row could not be created. Empty body (status code only).
- `503`: Route sources could not be assembled. Empty body (status code only).

---

[API](https://skmtc.dev/kairos/apis/kairos-order-execution-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-order-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-order-execution-api/revisions/9ba7d463d505?raw)