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

# Core concepts

> Integrations, markets, the buy, sell and manage verbs, simulate, signing, statuses and portfolio reads behind every Trade API integration.

Every Trade API integration uses the same objects: an integration you trade on, a market you trade, an action you request, the transactions you sign, and the balances, positions, orders and fills you read back. This page explains how they fit together. The full Trade API reference, with every argument, field and error, is published with its OpenAPI spec at launch.

<Note>
  The Trade API is not live yet. Names and shapes on this page come from the Trade API design and can change before launch. Hyperliquid perps are live today through the Perps API: see [Perps API today](/documentation/trade/perps#perps-api-today).
</Note>

## Providers, integrations, markets and accounts

| Object | ID | What it is |
| - | - | - |
| Provider | `providerId`, for example `hyperliquid` or `dinari` | The venue brand. It groups shared setup, such as trading keys and fees, and is enabled per project. |
| Integration | `integrationId`, for example `hyperliquid-perps` or `dinari-spot` | One product within a provider, with its own capabilities, arguments, fees and status. |
| Market | `marketId`, for example `hyperliquid-btc-usdc` | One tradeable instrument within an integration. |
| Account | `accountId` | The venue account behind an address. The API returns it on responses, and you never send it. |

Write requests take a `marketId`, or an `integrationId` when there is no market, such as a deposit. Read market IDs from `GET /v1/markets` and treat them as opaque, because the API mints them and never reuses or renames them. A market holds at most one position per account, so the `marketId` also identifies the position. Each integration stands alone: you list its markets and read its balances, positions, orders and fills by `integrationId`.

## Product types and asset classes

A market has a `type` of `perps`, `spot` or `predict`, and an `assetClass` of `crypto`, `stock`, `etf`, `fund` or `outcome`. Perps markets hold margin positions with leverage, while spot and prediction markets hold the token or shares the user bought. Each market publishes its trading constraints, its trading hours and a live price snapshot, so you can validate an order before you send it.

## Endpoints

```text theme={null}
Discovery
  GET  /v1/providers
  GET  /v1/integrations
  GET  /v1/integrations/{integrationId}
  GET  /v1/markets
  GET  /v1/markets/{marketId}
  GET  /v1/markets/{marketId}/candles
  GET  /v1/markets/{marketId}/book

Trading
  POST /v1/actions/buy | /v1/actions/sell
  POST /v1/actions/buy/simulate | /v1/actions/sell/simulate
  POST /v1/actions/manage
  POST /v1/transactions/{transactionId}/submit
  GET  /v1/actions/{actionId}
  GET  /v1/actions

Portfolio
  GET  /v1/balances
  GET  /v1/positions
  GET  /v1/orders
  GET  /v1/fills
```

`GET /v1/integrations/{integrationId}` tells you what an integration supports, including the arguments each action accepts.

## Buy, sell and manage

`buy` and `sell` are the two sides of an order. `buy` opens or adds to a long and `sell` opens or adds to a short, and the opposite side reduces an existing position. On spot and prediction markets, `buy` spends the quote token and `sell` sells a holding the user already has. Each request takes either an `amount`, which is what the user spends, or a `quantity` in base units such as contracts or shares. Reducing or closing a position always uses `quantity`.

```json theme={null}
POST /v1/actions/buy
{
  "marketId": "hyperliquid-xyz-tsla-usdc",
  "address": "0xAb5C...",
  "arguments": { "amount": "100", "leverage": 5 }
}
```

`manage` covers everything else, and its `action` field selects what to do. Position actions include closing a position, cancelling an order, setting a take profit and stop loss, and changing leverage or margin. Account actions include depositing, withdrawing, approving fees, registering a trading key and starting KYC with an issuer that needs it.

## Arguments: simple and advanced

The simple arguments are the same on every integration: a `marketId`, an `address` and an `amount` or `quantity` give you a trade at the market price. Advanced arguments, such as limit prices, leverage, take profit and stop loss, are optional, and each integration declares the ones it accepts in a schema, so the API rejects anything it does not support.

## Simulate

`POST /v1/actions/buy/simulate` and `POST /v1/actions/sell/simulate` take the same body as the action. They return a quote with the estimated price, output and fees, and a list of the requirements that stand between the user and the trade, such as funding, KYC, a trading key or a fee approval. Each requirement carries a pending action that resolves it. Complete the first requirement, wait for it to finish, and simulate again until nothing is left. Simulate is optional: if you call `buy` while a requirement is missing, it returns `412` with the same list.

## Pending actions

A pending action is a request the API has filled in for you. Positions, orders, balances and simulate requirements carry them, for example a `closePosition` on an open position or a `cancelOrder` on a resting order. Send one as it is to `POST /v1/actions/manage`, or to `buy` or `sell` when that is its action. When the user has to supply a value, such as a partial close quantity, the pending action lists only the fields you need to fill in. The server checks venue state again when it builds the action, so a stale pending action is rejected.

## Transactions and signing

Every action returns its full, ordered list of transactions up front. Each transaction says who signs it and in which format. The signer is either the user's wallet or a trading key that your client generates and holds. Yield.xyz never holds the user's keys or trading keys. Sign each transaction and send it to `POST /v1/transactions/{transactionId}/submit`. For chain transactions, you can broadcast yourself and send the transaction hash, or send the signed payload and let the API broadcast it. For venue transactions, you send the signed payload and Yield.xyz checks it against what it built before forwarding it to the venue. Submit the next transaction only after the previous one is confirmed.

Creating an action has no side effects. It does nothing until you sign it, and it expires after a short window.

## Status model

| Object | Statuses |
| - | - |
| Action | `CREATED`, `PROCESSING`, then `SUCCESS` or `FAILED` |
| Transaction | `CREATED`, `BROADCASTED`, then `CONFIRMED` or `FAILED` |
| Order | `open`, `partially_filled`, `filled`, and final states such as `canceled`, `rejected` and `expired` |

An action succeeds when all its transactions are confirmed and fails as soon as one fails or the action expires. Failed objects carry a reason that says whether you can retry with a new action. Poll `GET /v1/actions/{actionId}` until the action finishes, then follow any resting order through `GET /v1/orders`.

## Portfolio reads

`GET /v1/balances`, `/v1/positions`, `/v1/orders` and `/v1/fills` return the user's venue state for one `integrationId`, including activity placed outside the API, and each position, order and balance carries its pending actions.

## Next steps

<Columns cols={3}>
  <Card title="Perps" icon="chart-candlestick" href="/documentation/trade/perps">
    Perps on Hyperliquid and Lighter, and the mapping from the live Perps API.
  </Card>

  <Card title="Tokenized Stocks" icon="chart-line" href="/documentation/trade/tokenized-stocks">
    Quote-then-execute stock markets with issuer KYC and trading hours.
  </Card>

  <Card title="Coverage" icon="table" href="/documentation/trade/coverage">
    Every integration, its execution pattern and status.
  </Card>
</Columns>


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