Create Trade

curl --request POST \
  --url https://api.whop.com/api/v1/trades \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "type": "order",
  "amount": "<string>",
  "client_order_id": "<string>",
  "instrument_type": "perpetual",
  "leverage": 10,
  "market": "BTC",
  "metadata": {},
  "notional": "<string>",
  "order_type": "market",
  "price": "<string>",
  "reduce_only": true,
  "side": "buy",
  "size": "0.001",
  "slippage_bps": 123
}
'

import requests

url = "https://api.whop.com/api/v1/trades"

payload = {
    "account_id": "biz_xxxxxxxxxxxxxx",
    "type": "order",
    "amount": "<string>",
    "client_order_id": "<string>",
    "instrument_type": "perpetual",
    "leverage": 10,
    "market": "BTC",
    "metadata": {},
    "notional": "<string>",
    "order_type": "market",
    "price": "<string>",
    "reduce_only": True,
    "side": "buy",
    "size": "0.001",
    "slippage_bps": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account_id: 'biz_xxxxxxxxxxxxxx',
    type: 'order',
    amount: '<string>',
    client_order_id: '<string>',
    instrument_type: 'perpetual',
    leverage: 10,
    market: 'BTC',
    metadata: {},
    notional: '<string>',
    order_type: 'market',
    price: '<string>',
    reduce_only: true,
    side: 'buy',
    size: '0.001',
    slippage_bps: 123
  })
};

fetch('https://api.whop.com/api/v1/trades', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.whop.com/api/v1/trades",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account_id' => 'biz_xxxxxxxxxxxxxx',
    'type' => 'order',
    'amount' => '<string>',
    'client_order_id' => '<string>',
    'instrument_type' => 'perpetual',
    'leverage' => 10,
    'market' => 'BTC',
    'metadata' => [
        
    ],
    'notional' => '<string>',
    'order_type' => 'market',
    'price' => '<string>',
    'reduce_only' => true,
    'side' => 'buy',
    'size' => '0.001',
    'slippage_bps' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.whop.com/api/v1/trades"

	payload := strings.NewReader("{\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"type\": \"order\",\n  \"amount\": \"<string>\",\n  \"client_order_id\": \"<string>\",\n  \"instrument_type\": \"perpetual\",\n  \"leverage\": 10,\n  \"market\": \"BTC\",\n  \"metadata\": {},\n  \"notional\": \"<string>\",\n  \"order_type\": \"market\",\n  \"price\": \"<string>\",\n  \"reduce_only\": true,\n  \"side\": \"buy\",\n  \"size\": \"0.001\",\n  \"slippage_bps\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.whop.com/api/v1/trades")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"type\": \"order\",\n  \"amount\": \"<string>\",\n  \"client_order_id\": \"<string>\",\n  \"instrument_type\": \"perpetual\",\n  \"leverage\": 10,\n  \"market\": \"BTC\",\n  \"metadata\": {},\n  \"notional\": \"<string>\",\n  \"order_type\": \"market\",\n  \"price\": \"<string>\",\n  \"reduce_only\": true,\n  \"side\": \"buy\",\n  \"size\": \"0.001\",\n  \"slippage_bps\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.whop.com/api/v1/trades")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"type\": \"order\",\n  \"amount\": \"<string>\",\n  \"client_order_id\": \"<string>\",\n  \"instrument_type\": \"perpetual\",\n  \"leverage\": 10,\n  \"market\": \"BTC\",\n  \"metadata\": {},\n  \"notional\": \"<string>\",\n  \"order_type\": \"market\",\n  \"price\": \"<string>\",\n  \"reduce_only\": true,\n  \"side\": \"buy\",\n  \"size\": \"0.001\",\n  \"slippage_bps\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "amount": "25",
  "average_price": null,
  "client_order_id": null,
  "completed_at": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "failure_code": "market_unavailable",
  "filled_size": null,
  "funds_location": "wallet",
  "id": "tint_xxxxxxxxxxxxxx",
  "instrument_type": "perpetual",
  "leverage": 10,
  "market": "BTC",
  "metadata": {},
  "object": "trade",
  "order_type": "market",
  "price": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "reduce_only": null,
  "side": "buy",
  "size": null,
  "status": "pending",
  "status_detail": "partial_fill",
  "type": "order",
  "updated_at": "2026-01-01T12:00:00.000Z",
  "user_id": null
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

Trades

Create Trade

Places an order, closes a perpetual position, or deposits to or withdraws from the trading balance, from the Whop-managed wallet of an account or user. Answers 201 with the trade in pending; it runs in the background, so read it with GET /trades/:id until its status is completed, failed or in_review. Trades run alongside each other, except a second order on one market at a different leverage, which answers 409. A retry with the same Idempotency-Key returns the same trade.

POST

trades

Create Trade

curl --request POST \
  --url https://api.whop.com/api/v1/trades \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "type": "order",
  "amount": "<string>",
  "client_order_id": "<string>",
  "instrument_type": "perpetual",
  "leverage": 10,
  "market": "BTC",
  "metadata": {},
  "notional": "<string>",
  "order_type": "market",
  "price": "<string>",
  "reduce_only": true,
  "side": "buy",
  "size": "0.001",
  "slippage_bps": 123
}
'

import requests

url = "https://api.whop.com/api/v1/trades"

payload = {
    "account_id": "biz_xxxxxxxxxxxxxx",
    "type": "order",
    "amount": "<string>",
    "client_order_id": "<string>",
    "instrument_type": "perpetual",
    "leverage": 10,
    "market": "BTC",
    "metadata": {},
    "notional": "<string>",
    "order_type": "market",
    "price": "<string>",
    "reduce_only": True,
    "side": "buy",
    "size": "0.001",
    "slippage_bps": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account_id: 'biz_xxxxxxxxxxxxxx',
    type: 'order',
    amount: '<string>',
    client_order_id: '<string>',
    instrument_type: 'perpetual',
    leverage: 10,
    market: 'BTC',
    metadata: {},
    notional: '<string>',
    order_type: 'market',
    price: '<string>',
    reduce_only: true,
    side: 'buy',
    size: '0.001',
    slippage_bps: 123
  })
};

fetch('https://api.whop.com/api/v1/trades', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.whop.com/api/v1/trades",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'account_id' => 'biz_xxxxxxxxxxxxxx',
    'type' => 'order',
    'amount' => '<string>',
    'client_order_id' => '<string>',
    'instrument_type' => 'perpetual',
    'leverage' => 10,
    'market' => 'BTC',
    'metadata' => [
        
    ],
    'notional' => '<string>',
    'order_type' => 'market',
    'price' => '<string>',
    'reduce_only' => true,
    'side' => 'buy',
    'size' => '0.001',
    'slippage_bps' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.whop.com/api/v1/trades"

	payload := strings.NewReader("{\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"type\": \"order\",\n  \"amount\": \"<string>\",\n  \"client_order_id\": \"<string>\",\n  \"instrument_type\": \"perpetual\",\n  \"leverage\": 10,\n  \"market\": \"BTC\",\n  \"metadata\": {},\n  \"notional\": \"<string>\",\n  \"order_type\": \"market\",\n  \"price\": \"<string>\",\n  \"reduce_only\": true,\n  \"side\": \"buy\",\n  \"size\": \"0.001\",\n  \"slippage_bps\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.whop.com/api/v1/trades")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"type\": \"order\",\n  \"amount\": \"<string>\",\n  \"client_order_id\": \"<string>\",\n  \"instrument_type\": \"perpetual\",\n  \"leverage\": 10,\n  \"market\": \"BTC\",\n  \"metadata\": {},\n  \"notional\": \"<string>\",\n  \"order_type\": \"market\",\n  \"price\": \"<string>\",\n  \"reduce_only\": true,\n  \"side\": \"buy\",\n  \"size\": \"0.001\",\n  \"slippage_bps\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.whop.com/api/v1/trades")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"biz_xxxxxxxxxxxxxx\",\n  \"type\": \"order\",\n  \"amount\": \"<string>\",\n  \"client_order_id\": \"<string>\",\n  \"instrument_type\": \"perpetual\",\n  \"leverage\": 10,\n  \"market\": \"BTC\",\n  \"metadata\": {},\n  \"notional\": \"<string>\",\n  \"order_type\": \"market\",\n  \"price\": \"<string>\",\n  \"reduce_only\": true,\n  \"side\": \"buy\",\n  \"size\": \"0.001\",\n  \"slippage_bps\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "amount": "25",
  "average_price": null,
  "client_order_id": null,
  "completed_at": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "failure_code": "market_unavailable",
  "filled_size": null,
  "funds_location": "wallet",
  "id": "tint_xxxxxxxxxxxxxx",
  "instrument_type": "perpetual",
  "leverage": 10,
  "market": "BTC",
  "metadata": {},
  "object": "trade",
  "order_type": "market",
  "price": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "reduce_only": null,
  "side": "buy",
  "size": null,
  "status": "pending",
  "status_detail": "partial_fill",
  "type": "order",
  "updated_at": "2026-01-01T12:00:00.000Z",
  "user_id": null
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

Authorizations

Authorization

string

header

required

An Account API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Headers

Idempotency-Key

string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255

Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date

string

Pins the request to a dated API version.

Example:

"2026-10-15"

Body

application/json

account_id

string

required

The account or user whose wallet trades, prefixed biz_ or user_.

Example:

"biz_xxxxxxxxxxxxxx"

type

enum<string>

required

order places one order from the trading balance, setting cross leverage first on a perpetual; when the balance is short, it bridges the USDT0 it needs from the wallet first. deposit bridges amount USDT0 from the wallet to the trading balance. withdraw sends amount USDC (or all) from the trading balance back to the wallet. close closes the whole position in market with a market reduce-only order; when the account is then flat, a withdraw trade sends the trading balance back to the wallet.

Available options:

close,

order,

deposit,

withdraw

Example:

"order"

amount

string

Only for a deposit or withdraw, and required for both. For a deposit, the USDT0 to send from the wallet, with at most 6 decimals. For a withdraw, the USDC to send back, at least 1 with at most 6 decimals, or all.

client_order_id

string

Only for an order. Your own ID for the trade, 1 to 128 characters, unique for the account. Sending it again with the same order returns the same trade; with a different order it answers 409.

instrument_type

enum<string>

perpetual or spot. Required for an order. A spot order first switches the trading account to Hyperliquid's unified account mode, where spot and perpetuals share one USDC balance.

Available options:

perpetual,

spot

Example:

"perpetual"

leverage

integer

Only for a perpetual order. The cross leverage, from 1 to the market's maximum. Required unless reduce_only; not accepted on a reduce-only order.

Example:

10

market

string

The market: a perpetual such as BTC, or for spot a pair priced in USDC such as HYPE/USDC. Required for an order or close, and a close takes only a perpetual; not accepted for a deposit or withdraw.

Example:

"BTC"

metadata

object

Only for an order. Free-form string-to-string annotations: up to 50 keys of at most 40 characters, values up to 500 characters.

Show child attributes

notional

string

Only for an order. The order value in USD, as a decimal string; the size is rounded down to the market's decimals. Send exactly one of size or notional.

order_type

enum<string>

market fills now within slippage_bps of the mid price; limit fills now at price or better. Anything unfilled is canceled. Required for an order.

Available options:

market,

limit

Example:

"market"

price

string

Only for an order. The limit price in USD, as a decimal string Hyperliquid accepts without rounding. Required for a limit order; not accepted for a market order.

reduce_only

boolean

Only for a perpetual order. Only reduce an open position; defaults to false. A reduce-only order takes no leverage.

side

enum<string>

buy or sell. Required for an order.

Available options:

buy,

sell

Example:

"buy"

size

string

Only for an order. The size in units of the market, as a decimal string, with at most the market's size decimals. Send exactly one of size or notional. The order must be worth at least 10 USD, unless reduce-only, and at most 5000 USD.

Example:

"0.001"

slippage_bps

integer

Only for a market order or a close. The worst price as basis points from the mid price, from 1 to 1000; defaults to 100.

Response

trade created

account_id

string | null

required

The account that owns the trading wallet, prefixed biz_. null when a user owns it.

Example:

"biz_xxxxxxxxxxxxxx"

amount

string | null

required

The USDT0 that a deposit, or an order short of trading balance, sends from the wallet, or the USDC that a withdraw sends back, in native units, as a decimal string. A withdraw of all shows what it sent once it finishes. null otherwise.

Example:

"25"

average_price

string | null

required

The average fill price of the order, in USD, as a decimal string. null when it is not known.

Example:

null

client_order_id

string | null

required

The caller's own ID for the trade, unique for the account. null when none was sent.

Example:

null

completed_at

string | null

required

When the trade ended as completed or failed, as an ISO 8601 timestamp. null before that.

Example:

null

created_at

string

required

When the trade was created, as an ISO 8601 timestamp.

Example:

"2026-01-01T12:00:00.000Z"

failure_code

enum<string> | null

required

Why the trade failed, or null.

Available options:

market_unavailable,

leverage_too_high,

amount_too_small,

isolated_position_open,

trading_paused,

funding_failed,

margin_unavailable,

builder_fee_unapproved,

leverage_rejected,

leverage_unconfirmed,

order_rejected,

close_rejected,

return_failed,

withdraw_failed,

null

Example:

"market_unavailable"

filled_size

string | null

required

The size the order filled, in units of the market, as a decimal string. null until it fills.

Example:

null

funds_location

enum<string> | null

required

Where the money is when the trade did not complete as asked: wallet, trading_account, or unknown while a person checks it. null otherwise.

Available options:

wallet,

trading_account,

unknown,

null

Example:

"wallet"

string

required

Trade ID, prefixed tint_.

Example:

"tint_xxxxxxxxxxxxxx"

instrument_type

enum<string> | null

required

perpetual or spot for an order, perpetual for a close. null for a deposit or withdraw.

Available options:

perpetual,

spot,

null

Example:

"perpetual"

leverage

integer | null

required

The cross leverage set before an opening perpetual order. null for a spot order, close, deposit, withdraw or reduce-only order.

Example:

10

market

string | null

required

The market, for example BTC for a perpetual or HYPE/USDC for spot. null for a deposit or withdraw.

Example:

"BTC"

metadata

object

required

Free-form string-to-string annotations stored on the trade.

Example:

{}

object

enum<string>

required

Available options:

trade

Example:

"trade"

order_type

enum<string> | null

required

market or limit for an order. null otherwise.

Available options:

market,

limit,

null

Example:

"market"

price

object | null

required

The limit price of the order in USD. A market order's price is the mid price moved by slippage_bps. null for other types.

Show child attributes

reduce_only

boolean | null

required

Whether the order can only reduce a position. null for other types.

Example:

null

side

enum<string> | null

required

buy or sell for an order. null otherwise.

Available options:

buy,

sell,

null

Example:

"buy"

size

string | null

required

The order size in units of the market, as a decimal string. null for other types.

Example:

null

status

enum<string>

required

pending until the trade starts. processing while it runs, also while an order that did not fill sends the money it bridged in back to the wallet. completed when it did what was asked. failed when it did not; funds_location says where the money is. in_review when the outcome is unknown and a person checks it.

Available options:

pending,

processing,

in_review,

completed,

failed

Example:

"pending"

status_detail

enum<string> | null

required

partial_fill when the order filled only part of its size. null otherwise.

Available options:

partial_fill,

null

Example:

"partial_fill"

type

enum<string>

required

order places one order from the trading balance. deposit bridges USDT0 from the wallet to the trading balance. withdraw sends USDC from the trading balance back to the wallet. close closes the whole position in one market with a market reduce-only order; when the account is then flat, a withdraw trade sends the trading balance back to the wallet.

Available options:

close,

order,

deposit,

withdraw

Example:

"order"

updated_at

string

required

When the trade last changed, as an ISO 8601 timestamp.

Example:

"2026-01-01T12:00:00.000Z"

user_id

string | null

required

The user who owns the trading wallet, prefixed user_. null when an account owns it.

Example:

null

Introduction

Reference

Webhooks & Events

Core Resources

Notifications

Payments

Money

Commerce

Affiliate Program

Partners

Workforce

Tracking

Ads

Media

Identity

Developer

Create Trade

Authorizations

Headers

Body

Response