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

# Trading API introduction

> Estimate prices and place fill-or-kill orders on Uphold.

The Trading API lets you estimate the price of trading an asset and trade it between two accounts of a user, with orders that either trade the whole quantity or nothing.

> [!NOTE]
>
> This is a **preview** of the new Trading API. It is available in **Sandbox** only, where orders are simulated against a fixed order book, and it can change before release.

## Endpoints

| Endpoint | Description |
| - | - |
| [Estimate price](https://developer.uphold.com/rest-apis/trading-api/prices/estimate-price.md) | Estimate the price of trading a quantity of an asset. |
| [Create order](https://developer.uphold.com/rest-apis/trading-api/orders/create-order.md) | Place a fill-or-kill order. |
| [List orders](https://developer.uphold.com/rest-apis/trading-api/orders/list-orders.md) | List the orders of a user, newest first. |
| [Get order](https://developer.uphold.com/rest-apis/trading-api/orders/get-order.md) | Retrieve an order by its id. |
| [List order trades](https://developer.uphold.com/rest-apis/trading-api/orders/list-order-trades.md) | List the trades of an order. |

It uses the same OAuth 2.0 token endpoint and credentials as the [Core API](https://developer.uphold.com/rest-apis/core-api/authentication/request-oauth2-token.md), with its own scopes: `trading.prices:read`, `trading.orders:create` and `trading.orders:read`.

## Assets and pairs

An order trades one asset for another. The **base** asset is the one bought or sold and the **quote** asset is the one prices are expressed in, so for `BTC` and `USD` the base asset is `BTC`. A `quantity` is in the base asset and a `price` is in the quote asset per one unit of the base asset. All amounts are decimal strings.

The assets of an order are the ones of its `origin` and `destination` accounts. A pair that cannot be traded is refused with `asset_pair_not_supported`, and an amount that breaks a bound of the venue is refused with a `409` whose `details` name the rule and its `limit`.

## Price estimates

A price estimate is the volume-weighted price at which a `quantity` of the base asset would trade on a `side`, calculated from the order book. It is nonbinding, and the `snapshotAt` of the response says when the book was read. If the book cannot cover the quantity, the request fails with the depth that is available.

## Orders

An order debits the `origin` account and credits the `destination` account of the same user. The origin holds the base asset on a `sell` and the quote asset on a `buy`.

* `type` is `market`, which trades at the price the book offers, or `limit`, which trades only at its `price` or better. A limit order needs a `price`.
* `timeInForce` is `fok`: the whole quantity trades or nothing does.

### Retrying safely

The `clientOrderId` is an idempotency key you choose, up to 64 characters. Replaying it with the same payload returns the existing order with a `200`, and reusing it with a different payload is refused with a `409`. After a `5xx` or a timeout, replay the same `clientOrderId` before sending a new one, or the quantity may be traded twice.

### Order lifecycle

A `pending` order is still being processed, so retrieve it again until it is `closed`. A `closed` order is finished, whatever its outcome: read its `timeline` for it. A filled order has one trade, returned by [List order trades](https://developer.uphold.com/rest-apis/trading-api/orders/list-order-trades.md). A `failed` order may have traded, so do not send it again under a new `clientOrderId`.

## Trying it in Sandbox

Sandbox trades `BTC` and `USD` against a fixed order book, and needs a test user with a BTC account and a USD account. Send a new `clientOrderId` with every order.

These quantities force an outcome the book cannot produce by itself:

| Quantity (BTC) | Outcome |
| - | - |
| `0.000101` | The order stays `pending`. |
| `0.000102` | Rejected, with `venue-closed`. |
| `0.000103` | Failed. |
| `0.000104` | Canceled, with `insufficient-liquidity`. |
| `0.000429` | A `429` `too_many_requests`. |
| `0.000503` | A `503` `service_unavailable`. |

To try the reads, every user has six sample orders: [List orders](https://developer.uphold.com/rest-apis/trading-api/orders/list-orders.md) returns them, and you can get each one and read its trades.
