Sign in
Trades

Create Trade

Submits perpetual orders from a funded trading wallet. Send several limit orders for a ladder, or attach take_profit and stop_loss to a single entry order. Whop's builder fee is approved and attached automatically. The returned trop_ ID identifies the submission, not a position, and completed doesn't mean filled: check each order acknowledgement, and read live orders and positions from the account's trading field. Requires an Idempotency-Key. Early beta: email support@whop.com for access.

post/trades

Headers

Idempotency-Keystring required

Required. Reuse the same key when retrying, including after a submission_unknown outcome; a new key submits a new trade.

Request body

account_idstring required

The account or user that owns the trading wallet, prefixed biz_ or user_.

instrument_type'perpetual' required

The kind of instrument to trade.

metadataobject nullable

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

provider'hyperliquid' required
slippage_bpsinteger nullable

Default slippage cap in basis points for market orders and market-triggered take-profit and stop-loss.

Example request

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "instrument_type": "perpetual",
  "orders": [
    {
      "market": "ETH",
      "order_type": "limit",
      "price": "3000",
      "side": "buy",
      "size": "0.02",
      "stop_loss": {
        "trigger_price": "3300"
      },
      "take_profit": {
        "trigger_price": "3300"
      },
      "time_in_force": "add_liquidity_only"
    }
  ],
  "provider": "hyperliquid"
}

Response

submission recorded

account_idstring nullable required

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

completed_atstring nullable required

When the submission finished, as an ISO 8601 timestamp, or null while it is pending or its outcome is unknown.

created_atstring required

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

failure_code'pre_submission_error' | 'provider_rejected' | 'provider_outcome_unknown' | 'null' nullable required

Why the trade failed or has an unknown outcome, or null otherwise.

idstring required

Trade ID, prefixed trop_.

instrument_type'perpetual' required

The kind of instrument traded.

metadataobject required

String-to-string annotations you provided when submitting the trade.

object'trade' required
operation_type'create_orders' | 'cancel_orders' | 'update_leverage' required

create_orders places orders, cancel_orders cancels a submitted batch, and update_leverage sets a market's leverage.

provider'hyperliquid' required

Trading venue the trade was submitted to.

status'pending' | 'submitted' | 'completed' | 'failed' | 'submission_unknown' required

Submission status, not fill status. completed means the provider response was recorded, even if individual orders were rejected. Never resubmit a submission_unknown trade with a new idempotency key.

trade_idstring nullable required

For a cancellation, the ID of the canceled trade, prefixed trop_. null otherwise.

updated_atstring required

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

user_idstring nullable required

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

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "cancellations": [
    {
      "id": "trdcloid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "canceled"
    }
  ],
  "completed_at": "2026-01-01T12:00:00.000Z",
  "created_at": "2026-01-01T12:00:00.000Z",
  "failure_code": "pre_submission_error",
  "id": "trop_xxxxxxxxxxxxxx",
  "instrument_type": "perpetual",
  "leverage": {
    "leverage": 5,
    "margin_mode": "isolated",
    "market": "ETH"
  },
  "metadata": {},
  "object": "trade",
  "operation_type": "cancel_orders",
  "orders": [
    {
      "average_price": {
        "amount": "-2.50",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      },
      "hyperliquid": {
        "trigger_price": {
          "amount": "-2.50",
          "currency": "usd",
          "decimals": 2,
          "display_decimals": 2
        }
      },
      "object": "trading_order",
      "order_type": "limit",
      "price": {
        "amount": "-2.50",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      },
      "side": "buy",
      "status": "open"
    }
  ],
  "provider": "hyperliquid",
  "requested_orders": [
    {
      "client_order_id": "trdcloid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "market": "ETH",
      "order_type": "stop_loss",
      "parent_client_order_id": "trdcloid_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "price": {
        "amount": "-2.50",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      },
      "side": "sell",
      "size": "0.02",
      "trigger_price": {
        "amount": "-2.50",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      }
    }
  ],
  "status": "completed",
  "trade_id": "trop_xxxxxxxxxxxxxx",
  "updated_at": "2026-01-01T12:00:00.000Z"
}

Changes

Changed in 3 of the 74 revisions of this API.5

  • 78e1ed7366cd2See the full diff
    • ○

      the security scope crypto_wallet:trade was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope crypto_wallet:manage was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • 73dd0533cd812See the full diff
    • ○

      the security scope crypto_wallet:trade was added to the endpoint's security scheme bearerAuth

      api-security-scope-added

    • ○

      the security scope crypto_wallet:manage was removed from the endpoint's security scheme bearerAuth

      api-security-scope-removed

  • 86b97292852d1See the full diff
    • ○

      endpoint added

      endpoint-added

Of the 74 revisions, 1 has no diff computed.