---
title: "Sponsor gas and set the venue's required allowances on a wallet"
method: POST
path: "/exchanges/{exchange_id}/prepare-wallet"
tags: ["Exchanges"]
---

# Sponsor gas and set the venue's required allowances on a wallet

`POST /exchanges/{exchange_id}/prepare-wallet`

## Request

- Base URL: `https://execution.kairos.trade`
- URL: `https://execution.kairos.trade/exchanges/{exchange_id}/prepare-wallet`
- Auth: API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret`

The one-time onboarding step behind "enable trading": tops the wallet up with sponsored gas if it needs it, then sets every token allowance the venue's contracts require. Both legs are signed custodially with the user's delegated key.
**`wait_for_confirmation` defaults to `true`.** The call then blocks until the work completes and the response reports what actually happened. Passing `false` returns immediately with `confirmation_pending: true`, `success: true`, `gas_sponsored: false` and `allowances_set: 0` — **`success: true` there means "accepted", not "done"**, and a background failure is only logged, never surfaced. Poll the RPC query `exchange.getAllowances` to find out whether it worked.
The three identity fields are mandatory but are validated against the authenticated caller and the wallets it owns; they can confirm authority, never grant it.
Self-custody callers on the external-signing lane should use `POST /v2/onchain/intent` with `op: "approvals"` instead and pay their own gas.
**Auth & scope.** Requires `trade:execute`, the mutation gate (this endpoint spends gas-station funds, so a stolen JWT alone must not reach it), wallet ownership, and a current Turnkey policy version.

## Path parameters

- `exchange_id` string, required

## Request body

- OrderPrepareWalletRequest: Body for `POST /exchanges/{exchange_id}/prepare-wallet`. All three identity fields are mandatory and are VALIDATED against the authenticated caller — they can confirm authority, never grant it.
  - `user_id` string, required
  - `turnkey_org_id` string, required
  - `wallet_address` string, required: Must be a wallet owned by the authenticated caller.
  - `wait_for_confirmation` boolean, nullable: **Defaults to `true`** — the call blocks until gas sponsorship and allowances are confirmed. Pass `false` to fire-and-forget: the response returns immediately with `confirmation_pending: true`, `success: true` and zeroed result fields, and a background task does the work. A background failure is only logged; the caller is never told.

## Response `200`

Wallet prepared, or — when `wait_for_confirmation` was sent as false — preparation accepted and running in the background.

- OrderPrepareWalletResponse: Response for `POST /exchanges/{exchange_id}/prepare-wallet`.
  - `gas_sponsored` boolean, required: Always `false` when `confirmation_pending` is `true` — the work had not run yet.
  - `gas_tx_hash` string, nullable
  - `gas_amount` string, nullable: Present only when gas was actually sponsored.
  - `allowances_set` integer, required: Number of allowances set. Always `0` when `confirmation_pending` is `true`.
  - `confirmation_pending` boolean, required: `true` when the caller passed `wait_for_confirmation: false` and the preparation is still running in the background.
  - `success` boolean, required: Always `true` on a 200, INCLUDING the fire-and-forget path where nothing has been attempted yet. It is not evidence the wallet is ready.

## Other responses

- `400`: `user_id` is not a valid UUID, or an identity field is otherwise unusable.
- `401`: No valid credential presented — missing/invalid API-key headers or an invalid/expired session token.
- `403`: Missing `trade:execute` scope, API-key access to this provider disabled, an identity field that does not match the authenticated caller (`AUTH_IDENTITY_MISMATCH`), a wallet the caller does not own, or installed Turnkey policies behind the required version (`AUTH_POLICY_OUTDATED`).
- `404`: No pre-trade service is registered for this venue.
- `500`: Credentials or regional signing authority could not be resolved, or the wallet preparation itself failed. Only reachable on the blocking path — a background failure never surfaces to the caller.
- `503`: API-key access to this provider could not be checked (fails closed).

---

[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)