> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lean.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced: self-signed routed orders

> Sign the payment for a cross-venue buy yourself, in two calls.

> [!NOTE]
>
> Most programs don't need this page. `POST /v1/orders` already buys with cash held on the other
> venue, in one call. See [Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue). Use
> the flow below only if your program signs each payment with the account's wallet itself.

A routed order buys on Polymarket or Hyperliquid with cash held on the other of the two. Kalshi and
Polymarket US do not take routed orders. You name the venue whose cash pays
(`funding_venue`), Lean buys on the other venue, and you sign the payment before anything moves.
It takes two calls:

1. `POST /v1/routed-orders` quotes the route, books the order as `pending` and returns the payment
   to sign.
2. `POST /v1/routed-orders/{id}/execute` sends your signature. Lean then moves the cash and buys.

Routed orders are buys only. The key needs the `trade` and `route` scopes. See
[Authentication](https://docs.lean.xyz/authentication.md#create-a-key).

**1. Create the routed order**

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/routed-orders" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_order_id": "bot-2026-11-02-0001",
    "market_id": "'"$MARKET_ID"'",
    "quantity": "5",
    "limit_price": "0.42",
    "funding_venue": "hyperliquid"
  }'
```

| Field | Meaning |
| - | - |
| `client_order_id` | Required. Your ID for this order, as for `POST /v1/orders`. |
| `market_id` | A `mkt_…` ID from `GET /v1/markets`. |
| `quantity` | Shares, as a decimal string. |
| `limit_price` | The worst price per share you accept on the venue Lean buys on. |
| `funding_venue` | `hyperliquid` or `polymarket`: the venue whose cash pays. Lean buys on the other one. |

The response is the order, `pending`, with `route` and `payment`:

| Field | Meaning |
| - | - |
| `route` | The venues and costs, as on a [one-call order](https://docs.lean.xyz/orders.md#paying-from-the-other-venue): `funding_venue`, `execution_venue`, `notional_usd` (the most the payment can cost) and `costs` (`rebalance_fee_usd`, `gas_usd`, `activation_fee_usd` and their sum, `network_cost_usd`). |
| `payment.scheme` | What you sign: `hyperliquid_send_asset` or `polymarket_deposit_wallet_batch` for a live key, `lean_test_payment` for a test key. |
| `payment.signer_address` | The wallet that must sign. |
| `payment.typed_data` | The EIP-712 typed data to sign. A live payment is the venue transfer itself; a test payment is a Lean message naming this order. |
| `payment.agent_approval` | Polymarket funding only: set when the buying wallet first needs a Lean agent approved. Sign it too. Otherwise `null`. |

Only the response that created the order carries `payment`. A replay with the same
`client_order_id` returns the order with `payment: null`.

**2. Sign the payment**

Sign `payment.typed_data` as EIP-712 typed data with the wallet at `payment.signer_address`.
If `payment.agent_approval` is set, sign it as well. Sign and execute before the quote expires.

**3. Execute it**

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/v1/routed-orders/$ORDER_ID/execute" \
  -H "Authorization: Bearer $LEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "authorization": "signature",
    "payment_signature": "0x...",
    "agent_approval_signature": "0x..."
  }'
```

Leave out `agent_approval_signature` when the payment had no `agent_approval`. The response
is the order with `payment: null`. A test order is `filled`. A live order stays `pending`
while Lean moves the cash, then fills on the other venue. Sending the same authorization again
returns the order as it stands.

**4. Reconcile**

Read the order back with `GET /v1/orders/{id}` until it is final, as for any order. See
[Orders and idempotency](https://docs.lean.xyz/orders.md#reconcile).

## Letting Lean sign

Send `{ "authorization": "delegated" }` to the execute call instead of a signature, and Lean signs
the payment with the account's delegated signer, as `POST /v1/orders` does. A live key needs the
account to have trading enabled in the Lean app; otherwise the call returns `403 FORBIDDEN` with
`details.reason: "ACCOUNT_NOT_DELEGATED"`.

A routed order is authorized once. Sending a signature after a delegated authorization, or the
other way round, returns `409 CONFLICT` with `details.reason: "PAYMENT_ALREADY_AUTHORIZED"`.

## Errors

| HTTP | `code` | `details.reason` | When |
| - | - | - | - |
| 400 | `VALIDATION_ERROR` | `INVALID_SIGNATURE` | The signature is not a valid signature over the payment. |
| 400 | `VALIDATION_ERROR` | `SIGNER_MISMATCH` | The payment was signed by another wallet than `payment.signer_address`. |
| 403 | `FORBIDDEN` | | The key lacks the `route` scope. |
| 403 | `FORBIDDEN` | `ACCOUNT_NOT_DELEGATED` | `delegated` authorization on a live key, and the account has not enabled trading in the Lean app. |
| 404 | `NOT_FOUND` | | No routed order with this ID for this key, or, on create, no market with this ID. |
| 409 | `CONFLICT` | `QUOTE_EXPIRED` | The quote expired before the payment was authorized. Create a new routed order. |
| 409 | `CONFLICT` | `ROUTE_MOVED` | The route changed while it was quoted. Create a new routed order. |
| 409 | `CONFLICT` | `ORDER_NOT_PENDING` | The order is no longer waiting for its payment. |
| 409 | `CONFLICT` | `PAYMENT_ALREADY_AUTHORIZED` | The order was already authorized another way. |
| 409 | `CONFLICT` | `PAYMENT_MISMATCH` | The payment does not match the order or its trading account. |
| 409 | `CONFLICT` | `AGENT_APPROVAL_REQUIRED` | `delegated` authorization, and the buying wallet still needs its Lean agent approved. |
| 422 | `VALIDATION_ERROR` | `ROUTE_NOT_EXECUTABLE`, `LIMIT_BELOW_ROUTE_PRICE` | On create: no route can fill the whole quantity within the limit. There is no fallback venue. |
| 422 | `VALIDATION_ERROR` | `ORDER_NOTIONAL_LIMIT`, `DAILY_NOTIONAL_LIMIT` | A key or account limit. |
| 503 | `FEATURE_DISABLED` | `ROUTING_DISABLED`, `LIVE_TRADING_DISABLED`, `TRADING_PAUSED` | Routing or live trading is switched off, or this key or its account is paused. |
| 503 | `FEATURE_DISABLED` | `DELEGATED_ROUTE_SIGNING_DISABLED` | `delegated` authorization on a live key while Lean signing is switched off. Send a signature instead. |

See [Errors](https://docs.lean.xyz/errors.md) for the envelope and the other codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.