> ## Documentation Index > Fetch the complete documentation index at: https://docs.tradingapi.dev/llms.txt > Use this file to discover all available pages before exploring further. # Place an order > Places a market order, or an immediate-or-cancel limit order, sized by `value` in US dollars. The request waits for the result, up to 5 seconds by default, so most orders come back `filled` or `canceled` in this response. Change the wait with `Prefer: wait=N` (0 to 15 seconds). An order still `pending` after the wait keeps going; read it again later. `client_order_id` makes the request safe to retry. Sending the same body with the same `client_order_id` again never creates a second order: it returns the first one with `200` and `Idempotent-Replayed: true`. After a timeout, a dropped connection or a `503`, send the same request again. A `201` means an order was created, whatever its status. Read `status` to learn what happened. An error response means nothing was recorded, so fix the request and send it again. ## OpenAPI ````yaml /openapi.yaml post /v1/orders openapi: 3.1.0 info: title: Trading API license: name: Proprietary identifier: LicenseRef-Proprietary version: '1' summary: Trade perpetual futures on Hyperliquid with plain HTTP requests. description: > The Trading API places market orders on Hyperliquid perpetual futures and reports your positions, fills and balance. You never sign anything, manage nonces or look up asset indexes: send a market, a side and a value in US dollars. Every request authenticates with an API key created on the account page: `Authorization: Bearer tapi_…`. servers: - url: https://tradingapi.dev description: Production. Orders trade real money on Hyperliquid mainnet. security: - apiKey: [] tags: - name: Markets description: The markets you can trade, with their rules and current prices. - name: Orders description: Place, preview, list and look up orders. - name: Positions description: Your open positions, and closing them. - name: Account description: Your balance, the calling key, fills and withdrawals. paths: /v1/orders: post: tags: - Orders summary: Place an order description: > Places a market order, or an immediate-or-cancel limit order, sized by `value` in US dollars. The request waits for the result, up to 5 seconds by default, so most orders come back `filled` or `canceled` in this response. Change the wait with `Prefer: wait=N` (0 to 15 seconds). An order still `pending` after the wait keeps going; read it again later. `client_order_id` makes the request safe to retry. Sending the same body with the same `client_order_id` again never creates a second order: it returns the first one with `200` and `Idempotent-Replayed: true`. After a timeout, a dropped connection or a `503`, send the same request again. A `201` means an order was created, whatever its status. Read `status` to learn what happened. An error response means nothing was recorded, so fix the request and send it again. operationId: createOrder parameters: - $ref: '#/components/parameters/Prefer' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrderRequest' examples: market: summary: Buy $250 of BTC at market value: client_order_id: dca-btc-0927 market: BTC side: buy type: market value: '250.00' metadata: strategy: weekly-dca limit: summary: Sell $20 of ETH, but not below $2,690 value: client_order_id: eth-trim-0927-1 market: ETH side: sell type: limit price: '2690' value: '20.00' reduce_only: summary: Reduce a TSLA long by $15, never flipping value: client_order_id: tsla-trim-7 market: TSLA side: sell type: market value: '15.00' reduce_only: true responses: '200': description: >- The `client_order_id` already names an identical order. This is that order; nothing new was placed. headers: Idempotent-Replayed: description: Always `true` on this response. schema: type: string enum: - 'true' content: application/json: schema: $ref: '#/components/schemas/Order' examples: replay: $ref: '#/components/examples/OrderFilled' '201': description: >- The order was created by this request. Read `status` for the outcome. headers: Preference-Applied: $ref: '#/components/headers/PreferenceApplied' content: application/json: schema: $ref: '#/components/schemas/Order' examples: filled: $ref: '#/components/examples/OrderFilled' partial: $ref: '#/components/examples/OrderPartial' pending: $ref: '#/components/examples/OrderPending' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/KeyLimit' '404': $ref: '#/components/responses/MarketNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Unprocessable' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: parameters: Prefer: name: Prefer in: header required: false description: >- `wait=N`: wait up to N seconds (0 to 15) for the order to finish. The default is `wait=5`. schema: type: string example: wait=5 schemas: CreateOrderRequest: type: object required: - client_order_id - market - side - type - value additionalProperties: false properties: client_order_id: $ref: '#/components/schemas/ClientOrderId' market: type: string description: >- A market symbol from `GET /v1/markets`. Case-insensitive, and must match exactly. example: BTC side: $ref: '#/components/schemas/Side' type: $ref: '#/components/schemas/OrderType' value: $ref: '#/components/schemas/Usd' description: >- How much to buy or sell, in USD, with at most 2 decimals. The size is this value divided by the order's price limit, rounded down to the market's size step, so the order never costs more than this. example: '250.00' price: $ref: '#/components/schemas/Decimal' description: >- Required for `limit` orders, refused for `market`. The worst price you accept. Rounded in your favour to the market's price precision. reduce_only: type: boolean default: false description: >- When `true`, the order can only reduce your position. It never opens one or flips a long into a short. metadata: $ref: '#/components/schemas/Metadata' Order: type: object required: - object - id - client_order_id - market - side - type - status - status_reason - requested_value - requested_percent - reduce_only - size - price - price_limit - time_in_force - filled_size - average_fill_price - filled_value - fee - position_effect - summary - notes - metadata - created_at - updated_at - completed_at properties: object: type: string const: order id: type: string description: Our ID for the order. client_order_id: $ref: '#/components/schemas/ClientOrderId' market: type: string side: $ref: '#/components/schemas/Side' type: $ref: '#/components/schemas/OrderType' status: $ref: '#/components/schemas/OrderStatus' status_reason: $ref: '#/components/schemas/StatusReason' requested_value: type: - string - 'null' description: >- The `value` you sent. `null` for a close by percent or of the whole position. requested_percent: type: - string - 'null' description: The `percent` of a close. `null` otherwise. reduce_only: type: boolean size: type: - string - 'null' description: >- The size sent to the market, in the market's units. `null` until the order is sized. price: type: - string - 'null' description: Your limit price as used. `null` for market orders. price_limit: type: - string - 'null' description: >- The worst price the order could fill at. For market orders, 0.5% from the price when it was placed. time_in_force: type: string enum: - ioc description: Always `ioc` (immediate or cancel) for now. filled_size: $ref: '#/components/schemas/Decimal' average_fill_price: type: - string - 'null' filled_value: type: - string - 'null' description: The USD value that filled. fee: type: - string - 'null' description: >- Total fees paid, in USD, exact to 6 decimals. Can arrive shortly after the order finishes. position_effect: $ref: '#/components/schemas/PositionEffect' summary: type: string description: >- What happened, in plain English. For people and language models; branch on fields, not on this text. notes: type: array items: $ref: '#/components/schemas/Note' metadata: $ref: '#/components/schemas/Metadata' timeline: type: array description: Present only with `expand[]=timeline`. items: $ref: '#/components/schemas/TimelineEntry' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' completed_at: type: - string - 'null' format: date-time description: When the order reached a final status. ClientOrderId: type: string pattern: ^[A-Za-z0-9._:-]{1,64}$ description: >- Your ID for the order, 1 to 64 characters of letters, digits, `.`, `_`, `:` and `-`. Unique per account, forever. Side: type: string enum: - buy - sell OrderType: type: string enum: - market - limit description: > `market` fills now at the best available prices, within 0.5% of the current price. `limit` fills now at your `price` or better; whatever cannot fill at once is canceled. Usd: type: string description: US dollars as a decimal string, for example `"248.68"`. pattern: ^-?[0-9]+(\.[0-9]+)?$ Decimal: type: string description: >- A decimal number as a string, for example `"250.00"`. Requests also accept a JSON number. pattern: ^-?[0-9]+(\.[0-9]+)?$ Metadata: type: object description: >- Up to 20 keys of your own, returned with the order and never interpreted. Keys up to 40 characters of letters, digits, `_`, `.` and `-`; string values up to 500 characters. maxProperties: 20 additionalProperties: type: string maxLength: 500 OrderStatus: type: string enum: - pending - filled - canceled - rejected description: > `pending`: recorded, and possibly sent; the outcome is not known yet. `filled`: the whole size filled. `canceled`: filled partly or not at all; the rest found no price within the limit. `rejected`: refused; nothing filled. More statuses will be added. Treat a status you don't recognise as not finished. StatusReason: type: - object - 'null' required: - code - message description: Why an order is `canceled` or `rejected`. `null` otherwise. properties: code: type: string enum: - no_liquidity_in_limit - ioc_remainder - insufficient_balance - order_below_minimum - order_above_maximum - reduce_only_would_increase - no_position - market_unavailable - deadline_passed - refused_by_safeguards - not_sent - rejected_by_market - awaiting_market message: type: string description: What happened, in a sentence, with the numbers involved. PositionEffect: type: - string - 'null' enum: - open - increase - reduce - close - flip - null description: What the order did to your position. `null` when nothing filled. Note: type: object required: - code - message description: > Something worth knowing about a response that did not stop it. `available_low`, `partial_fill_likely` and `trading_approval_expiring` appear on previews only. properties: code: type: string enum: - size_rounded - price_rounded - position_flipped - position_closed - available_low - partial_fill_likely - trading_approval_expiring message: type: string TimelineEntry: type: object required: - at - event - message properties: at: $ref: '#/components/schemas/Timestamp' event: type: string enum: - received - admitted - leverage_set - sent - filled - partially_filled - canceled - rejected - fees_recorded message: type: string Timestamp: type: string format: date-time description: >- RFC 3339 in UTC with milliseconds, for example `2026-09-27T14:30:00.123Z`. ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/Error' Error: type: object required: - type - code - message - param - hint - details - errors - retryable - doc_url properties: type: type: string enum: - invalid_request - authentication - permission - not_found - conflict - unprocessable - rate_limited - unavailable - internal description: The kind of error. It determines the HTTP status. code: type: string description: >- A stable identifier for the error. Branch on this. New codes may be added. message: type: string description: What was wrong, with the values involved. param: type: - string - 'null' description: The request field at fault, as a JSON path, or `null`. hint: type: - string - 'null' description: One concrete way to fix the request. details: type: object description: The numbers and values the message refers to, as fields. additionalProperties: true errors: type: array description: Every field error, when `code` is `invalid_fields`. Empty otherwise. items: $ref: '#/components/schemas/Error' retryable: type: boolean description: Whether the same request can succeed later, unchanged. retry_after: $ref: '#/components/schemas/Timestamp' description: When a retry can succeed, if known. doc_url: type: string format: uri examples: OrderFilled: summary: A market buy that filled value: object: order id: ord_7kq2m4x9h3v8r5t2w6y4n8p3za client_order_id: dca-btc-0927 market: BTC side: buy type: market status: filled status_reason: null requested_value: '250.00' requested_percent: null reduce_only: false size: '0.00296' price: null price_limit: '84430' time_in_force: ioc filled_size: '0.00296' average_fill_price: '84012.4' filled_value: '248.68' fee: '0.360581' position_effect: open summary: >- Bought 0.00296 BTC for $248.68 at an average of $84,012.40 in 1 fill, fee $0.36. You asked for $250.00; the order was sized so it could not cost more even at its price limit of $84,430. You are now long 0.00296 BTC. notes: - code: size_rounded message: >- $250.00 at a price limit of $84,430 is 0.0029610 BTC; rounded down to 0.00296, the nearest 0.00001. metadata: strategy: weekly-dca created_at: '2026-09-27T14:30:00.123Z' updated_at: '2026-09-27T14:30:00.618Z' completed_at: '2026-09-27T14:30:00.618Z' OrderPartial: summary: A market buy that filled partly value: object: order id: ord_3mf8q2k4x7w9r5t2v6y4n8p3zb client_order_id: dca-btc-0928 market: BTC side: buy type: market status: canceled status_reason: code: ioc_remainder message: >- 0.00240 of 0.00296 BTC filled; the rest found no price within your limit of $84,430 and was canceled. requested_value: '250.00' requested_percent: null reduce_only: false size: '0.00296' price: null price_limit: '84430' time_in_force: ioc filled_size: '0.0024' average_fill_price: '84012.4' filled_value: '201.63' fee: '0.292363' position_effect: increase summary: >- Bought 0.00240 of 0.00296 BTC ($201.63) in 2 fills at an average of $84,012.40; the rest found no price within your limit of $84,430 and was canceled. You are now long 0.00536 BTC. notes: [] metadata: {} created_at: '2026-09-28T09:12:41.020Z' updated_at: '2026-09-28T09:12:41.544Z' completed_at: '2026-09-28T09:12:41.544Z' OrderPending: summary: An order still waiting on the market value: object: order id: ord_5nd2r7k4x9w3m5t2v6y4q8p3zc client_order_id: sol-entry-12 market: SOL side: buy type: market status: pending status_reason: null requested_value: '20.00' requested_percent: null reduce_only: false size: '0.16' price: null price_limit: '122.95' time_in_force: ioc filled_size: '0' average_fill_price: null filled_value: null fee: null position_effect: null summary: Buying $20.00 of SOL; waiting for the market to confirm. notes: [] metadata: {} created_at: '2026-09-28T10:02:13.411Z' updated_at: '2026-09-28T10:02:13.690Z' completed_at: null headers: PreferenceApplied: description: The wait that was applied, for example `wait=5`. schema: type: string responses: InvalidRequest: description: >- The request is malformed or breaks a rule. Nothing was recorded; fix it and send it again. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_fields: summary: Several fields at once value: error: type: invalid_request code: invalid_fields message: 3 fields are invalid. param: null hint: Fix each field listed in errors. details: {} errors: - type: invalid_request code: invalid_value message: >- side is "long". Orders use "buy" or "sell"; "long" describes a position. param: side hint: 'To open a long, send "side": "buy".' details: {} errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#invalid_value - type: invalid_request code: unknown_field message: amount is not a field of this request. param: amount hint: Did you mean value? It is the order's size in USD. details: {} errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#unknown_field - type: invalid_request code: missing_field message: value is required. param: value hint: >- Send how much to buy or sell in USD, for example "value": "25.00". details: {} errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#missing_field retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#invalid_fields order_below_minimum: summary: Under the minimum after rounding value: error: type: invalid_request code: order_below_minimum message: >- A value of $10.00 buys 0.00011 BTC after rounding down to BTC's 0.00001 size step, which is worth $9.29 at the price limit of $84,430. The minimum is $10.00. param: value hint: Send a value of at least $10.14. details: value: '10.00' value_after_rounding: '9.29' min_value: '10.00' smallest_passing_value: '10.14' errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#order_below_minimum Unauthorized: description: No valid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_api_key: value: error: type: authentication code: invalid_api_key message: This API key is not valid. It may have been revoked. param: null hint: >- Send a current key as Authorization: Bearer tapi_…. Keys are created and revoked on the account page. details: {} errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#invalid_api_key KeyLimit: description: The calling key's limits refuse this order. Nothing was recorded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: key_daily_limit_exceeded: value: error: type: permission code: key_daily_limit_exceeded message: >- This key may place $100.00 of orders per 24 hours. $92.40 is used, so $7.60 remains, which is less than the $10.00 minimum order. param: value hint: >- $40.00 frees up at 14:05 UTC, when an earlier order leaves the 24-hour window. The account owner can raise the limit on the account page. details: limit: '100.00' used: '92.40' remaining: '7.60' next_release: at: '2026-09-28T14:05:11.000Z' value: '40.00' errors: [] retryable: true retry_after: '2026-09-28T14:05:11.000Z' doc_url: >- https://docs.tradingapi.dev/api-reference/errors#key_daily_limit_exceeded MarketNotFound: description: The market does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: The request conflicts with an earlier one or with the account's state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: client_order_id_reused: value: error: type: conflict code: client_order_id_reused message: >- client_order_id "dca-btc-0927" already names order ord_7kq2m4x9h3v8r5t2w6y4n8p3za (buy $250.00 of BTC, filled at 14:30 UTC). This request differs in side. param: client_order_id hint: >- If you meant a new order, use a new client_order_id. If you are retrying, send the original body unchanged. details: order_id: ord_7kq2m4x9h3v8r5t2w6y4n8p3za differs: - side errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#client_order_id_reused Unprocessable: description: >- The request is valid but cannot be carried out given your account or the market right now. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficient_balance: value: error: type: unprocessable code: insufficient_balance message: >- Buying $2,500.00 of ETH needs $2,500.00 plus about $3.63 in fees. You have $312.40 available. param: value hint: Send a value of at most $311.94, or deposit more. details: required: '2503.63' available: '312.40' max_value: '311.94' errors: [] retryable: false doc_url: >- https://docs.tradingapi.dev/api-reference/errors#insufficient_balance RateLimited: description: >- The key made too many requests. Each key may make 10 requests at once, then 5 a second. Nothing was done; retry after `Retry-After` seconds. headers: Retry-After: description: The seconds to wait before retrying, always `1`. schema: type: string enum: - '1' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rate_limited: value: error: type: rate_limited code: rate_limited message: This key made too many requests; retry in 1 s. param: null hint: >- Slow down: each key may make 10 requests at once, then 5 a second. details: {} errors: [] retryable: true retry_after: '2026-09-28T14:05:12.000Z' doc_url: >- https://docs.tradingapi.dev/api-reference/errors#rate_limited Unavailable: description: A service we depend on failed. Retry the same request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unavailable: value: error: type: unavailable code: unavailable message: The exchange could not be reached. param: null hint: >- Retry the same request with the same client_order_id; an order may already have been recorded. details: {} errors: [] retryable: true doc_url: https://docs.tradingapi.dev/api-reference/errors#unavailable securitySchemes: apiKey: type: http scheme: bearer bearerFormat: tapi_… description: >- An API key from the account page, sent as `Authorization: Bearer tapi_…`. ````