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.
Providers, integrations, markets and accounts
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 atype 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
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.
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: amarketId, 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 aclosePosition 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 toPOST /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
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
Perps
Perps on Hyperliquid and Lighter, and the mapping from the live Perps API.
Tokenized Stocks
Quote-then-execute stock markets with issuer KYC and trading hours.
Coverage
Every integration, its execution pattern and status.