API docs by Redocly

dYdX v5 API (0.1.0)

Download OpenAPI specification:Download

REST API for the dYdX v5 exchange. Provides endpoints for order management, market data, and account onboarding.

Authentication

Private endpoints use an X-API-Key header. Obtain a key via POST /api/v5/createAPIKey. In production the gateway requires this header; local development may run with API keys optional (see security on each operation: apiKey or empty).

Account-scoped requests

For fills, positions, orders, open orders, placing an order, and canceling an order, you must also pass address as a query parameter with the same master Ethereum address returned for that API key from POST /api/v5/createAPIKey. The server rejects mismatches (HTTP 403). WebSocket placeOrder / cancel / batchPlaceOrders / batchCancelOrders / modifyOrder use the same value in the JSON payload field address.

Public

Unauthenticated endpoints — market data and health checks.

Service info

Returns service metadata, health status, and available endpoints.

Responses

Response samples

Content type
application/json
{
  • "service": "string",
  • "version": "string",
  • "status": "string",
  • "health": {
    },
  • "endpoints": [
    ]
}

Health check

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Get L2 orderbook snapshot

Returns the current L2 orderbook snapshot for a market, truncated to the requested number of levels per side.

path Parameters
market
required
string
Examples:
  • BTC-PERP -

Market identifier.

query Parameters
n_levels
integer [ 1 .. 100 ]
Default: 20

Number of price levels to return per side (bids and asks). Defaults to 20, maximum 100.

Responses

Response samples

Content type
application/json
{
  • "bids": [
    ],
  • "asks": [
    ],
  • "last_sequence_id": 0,
  • "global_sequence_id": 0,
  • "timestamp": 0
}

Get best bid/offer

Returns the best bid and best ask for a market, derived from the orderbook snapshot. Returns null for best_bid/best_ask when no data is available.

path Parameters
market
required
string
Examples:
  • BTC-PERP -

Market identifier.

Responses

Response samples

Content type
application/json
{
  • "best_bid": {
    },
  • "best_ask": {
    },
  • "last_sequence_id": 0,
  • "global_sequence_id": 0,
  • "timestamp": 0
}

Get all mid prices

Returns mids from the precomputed Redis aggregate (mids:all) written by go-core. Markets with no bid, no ask, or no top-of-book return an empty string for that key.

Responses

Response samples

Content type
application/json
{
  • "mids": {
    },
  • "global_sequence_id": 0
}

Get markets

Returns all markets with details. Optionally filter by market name.

query Parameters
market
string
Enum: "BTC-PERP" "ETH-PERP"
Examples:
  • market=BTC-PERP -

Optional market filter.

Responses

Response samples

Content type
application/json
{
  • "markets": [
    ]
}

Private

Authenticated endpoints — use X-API-Key where the gateway enforces it; OpenAPI lists apiKey and {} so clients may call without a key when the deployment allows it. Fills, positions, orders, open orders, place order, and cancel also require query parameter address matching the key's master Ethereum address.

Get open orders

Returns open orders for the account associated with X-API-Key. Requires address query parameter matching that key's master Ethereum address.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

count
integer
Examples:
  • count=100 -

Maximum number of orders to return.

offset
integer
Examples:
  • offset=0 -

Number of orders to skip for pagination.

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Get all orders

Returns all orders (including open, filled, and canceled) for the account associated with X-API-Key. Requires address query parameter matching that key's master Ethereum address.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

count
integer
Examples:
  • count=100 -

Maximum number of orders to return.

offset
integer
Examples:
  • offset=0 -

Number of orders to skip for pagination.

Responses

Response samples

Content type
application/json
{
  • "orders": [
    ]
}

Get fills

Returns fill / trade history for the account associated with X-API-Key. Requires address query parameter matching that key's master Ethereum address.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

count
integer >= 1

Maximum number of fills to return (default 100).

from
integer <int64>

Start timestamp filter (epoch ms, inclusive).

to
integer <int64>

End timestamp filter (epoch ms, inclusive).

Responses

Response samples

Content type
application/json
{
  • "fills": [
    ]
}

Get positions

Returns all open positions for the account associated with X-API-Key. Requires address query parameter matching that key's master Ethereum address.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Responses

Response samples

Content type
application/json
{
  • "positions": [
    ]
}

Get account

Returns account information for the authenticated API key (balance, collateral, open positions). Requires address query parameter matching that key's master Ethereum address.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Responses

Response samples

Content type
application/json
{
  • "account_index": 10,
  • "ethereum_address": "string",
  • "equity": "string",
  • "free_collateral": "string",
  • "net_deposits": "100000",
  • "pending_deposits": "string",
  • "pending_withdrawals": "string",
  • "positions": {
    }
}

Get order status

Returns the status of a specific order by order ID.

Authorizations:
apiKeyNone
path Parameters
order_id
required
string

System-generated order ID (hex string).

Responses

Response samples

Content type
application/json
{
  • "order_id": "string",
  • "client_id": "string",
  • "market_id": 0,
  • "market_display_name": "BTC-PERP",
  • "side": "BUY",
  • "type": "LIMIT",
  • "status": "PENDING",
  • "price": "string",
  • "original_size": "string",
  • "filled_size": "string",
  • "remaining_size": "string",
  • "avg_fill_price": "string",
  • "time_in_force": "GTC",
  • "good_til_time": "string",
  • "trigger_price": "string",
  • "tpsl_type": "STOP_LOSS",
  • "rejection_reason": "POST_ONLY_WOULD_CROSS",
  • "created_at": 0,
  • "updated_at": 0,
  • "sequence_number": 0
}

Place order

Place a single order. Requires address query parameter matching the master Ethereum address for X-API-Key (same as POST /api/v5/createAPIKey response).

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Request Body schema: application/json
required
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match POST /api/v5/createAPIKey for the same key). May be sent here and/or as the address query parameter; if both are set, they must match.

market_id
required
integer (MarketId)
Enum: 0 1

Perpetual market identifier. 0 = BTC-PERP, 1 = ETH-PERP. Used for orders, positions, funding, and market metadata.

account_index
required
integer (AccountIndex) [ 0 .. 10 ]

Account index (account index, 0–10). Identifies the account for orders, positions, fills, and API keys.

order_side
required
string (OrderSide)
Enum: "BUY" "SELL"
order_type
required
string (OrderType)
Enum: "LIMIT" "MARKET"

Execution style of the order. Use tpsl_type to mark an order as stop-loss or take-profit.

quantity
required
string non-empty ^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$...

Order size in human-readable base-asset units (e.g. "0.1" for 0.1 BTC). Must be a positive value divisible by the market's step size (see GET /markets).

price
required
string non-empty ^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$...

Price in human-readable USD (e.g. "50000.5"). Must be a positive value divisible by the market's tick size. For MARKET orders, set to "0".

time_in_force
required
string (TimeInForce)
Enum: "GTC" "IOC" "FOK" "ALO"

GTC = Good Till Canceled, IOC = Immediate or Cancel, FOK = Fill or Kill, ALO = Add Liquidity Only (post-only)

min_size
string or null

Minimum fill size in human-readable base-asset units.

stop_price
string non-empty

Trigger price in human-readable USD. Required when tpsl_type is set; otherwise omit this field.

tpsl_type
string (TpslType)
Enum: "STOP_LOSS" "TAKE_PROFIT"

Set to STOP_LOSS or TAKE_PROFIT to mark this as a trigger order. Requires stop_price; for LIMIT execution, price is also required.

client_id
string or null

Client-provided order ID for tracking.

client_time
string or null

Client-side timestamp (epoch ms as string).

fill_mode
string or null

Fill mode.

reduce_only
boolean or null
Default: false

If true, the order can only reduce an existing position.

timestamp
required
integer <int64> [ 1 .. 9223372036854776000 ]

Signature timestamp (epoch ms). Must be > 0.

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "market_id": 0,
  • "account_index": 10,
  • "order_side": "BUY",
  • "order_type": "LIMIT",
  • "quantity": "0.1",
  • "price": "50000.5",
  • "time_in_force": "GTC",
  • "min_size": "string",
  • "stop_price": "string",
  • "tpsl_type": "STOP_LOSS",
  • "client_id": "string",
  • "client_time": "string",
  • "fill_mode": "string",
  • "reduce_only": false,
  • "timestamp": 1
}

Response samples

Content type
application/json
{
  • "address": "0x1234567890abcdef1234567890abcdef12345678",
  • "account_index": 10,
  • "order_id": "a1b2c3d4e5f67890",
  • "client_id": "string",
  • "market_id": 0,
  • "market_display_name": "BTC-PERP",
  • "side": "BUY",
  • "type": "LIMIT",
  • "quantity": "string",
  • "price": "string",
  • "status": "PENDING",
  • "created_at": 0
}

Place batch orders

Place up to 100 orders in a single request. Requires address query parameter matching the master Ethereum address for X-API-Key (same as single POST /api/v5/placeOrder).

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Request Body schema: application/json
required
required
Array of objects (OrderRequest) [ 1 .. 10 ] items

Array of 1-100 orders.

Responses

Request samples

Content type
application/json
{
  • "orders": [
    ]
}

Response samples

Content type
application/json
{
  • "responses": [
    ]
}

Cancel order

Cancel an open order by ID. Requires address query parameter matching the master Ethereum address for X-API-Key.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Request Body schema: application/json
required
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match POST /api/v5/createAPIKey for the same key). May be sent here and/or as the address query parameter; if both are set, they must match.

market_id
required
integer (MarketId)
Enum: 0 1

Perpetual market identifier. 0 = BTC-PERP, 1 = ETH-PERP. Used for orders, positions, funding, and market metadata.

account_index
required
integer (AccountIndex) [ 0 .. 10 ]

Account index (account index, 0–10). Identifies the account for orders, positions, fills, and API keys.

order_id
required
string non-empty

Server-generated order ID to cancel (hex string).

valid_until
integer or null <int64>

Optional valid-until timestamp.

timestamp
integer <int64> [ 1 .. 9223372036854776000 ]

Optional request timestamp (epoch ms).

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "market_id": 0,
  • "account_index": 10,
  • "order_id": "string",
  • "valid_until": 0,
  • "timestamp": 1
}

Response samples

Content type
application/json
{
  • "address": "0x1234567890abcdef1234567890abcdef12345678",
  • "account_index": 10,
  • "order_id": "string",
  • "market_id": 0,
  • "market_display_name": "BTC-PERP",
  • "status": "PENDING",
  • "update_time": 0
}

Batch cancel orders

Cancel up to 100 orders in a single request. Requires address query parameter matching the master Ethereum address for X-API-Key.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Request Body schema: application/json
required
required
Array of objects (CancelOrderRequest) [ 1 .. 100 ] items

Array of 1-100 cancel requests.

Responses

Request samples

Content type
application/json
{
  • "cancels": [
    ]
}

Response samples

Content type
application/json
{
  • "responses": [
    ]
}

Modify order

Modify the quantity of an open order.

Authorizations:
apiKeyNone
Request Body schema: application/json
required
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match POST /api/v5/createAPIKey for the same key).

account_index
required
integer (AccountIndex) [ 0 .. 10 ]

Account index (account index, 0–10). Identifies the account for orders, positions, fills, and API keys.

market_id
required
integer (MarketId)
Enum: 0 1

Perpetual market identifier. 0 = BTC-PERP, 1 = ETH-PERP. Used for orders, positions, funding, and market metadata.

order_id
required
string non-empty

Server-generated order ID to modify (hex string).

quantity
required
string non-empty ^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$...

New size in human-readable base-asset units (e.g. "0.5" for 0.5 BTC).

price
required
string non-empty ^(0\.[0-9]*[1-9][0-9]*|[1-9][0-9]*\.?[0-9]*)$...

New price in human-readable USD (e.g. "50000.5").

side
required
string (OrderSide)
Enum: "BUY" "SELL"
time_in_force
required
string (TimeInForce)
Enum: "GTC" "IOC" "FOK" "ALO"

GTC = Good Till Canceled, IOC = Immediate or Cancel, FOK = Fill or Kill, ALO = Add Liquidity Only (post-only)

reduce_only
boolean or null
Default: false

If true, the order can only reduce an existing position.

client_id
string or null

Client-provided tracking ID (max 36 chars).

client_time
string or null

Client-side timestamp (epoch ms as string).

timestamp
required
integer <int64> [ 1 .. 9223372036854776000 ]

Signature timestamp (epoch ms). Must be > 0.

Responses

Request samples

Content type
application/json
{
  • "address": "string",
  • "account_index": 10,
  • "market_id": 0,
  • "order_id": "string",
  • "quantity": "string",
  • "price": "string",
  • "side": "BUY",
  • "time_in_force": "GTC",
  • "reduce_only": false,
  • "client_id": "string",
  • "client_time": "string",
  • "timestamp": 1
}

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "client_time": 0,
  • "order_id": "string"
}

Get API keys

Returns all API keys associated with the given address.

Authorizations:
apiKeyNone
query Parameters
address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Master Ethereum address for this API key (must match ethereum_address from POST /api/v5/createAPIKey for the same key). Required on REST for account-scoped reads and for place/cancel. Invalid hex → 400; mismatch with key → 403.

Responses

Response samples

Content type
application/json
{
  • "api_keys": [
    ]
}

Onboarding

Account and API key management.

Create API key

Create an API key for the ethereum address. No address or account parameter is required; all keys are associated with the master account.

Request Body schema: application/json
required
ethereum_address
required
string (EthereumAddressHex) ^(0x|0X)?[0-9a-fA-F]{40}$

Ethereum address to associate with the account.

public_key
required
string non-empty ^[0-9a-fA-F]+$

Hex-encoded Ed25519 public key. Becomes the API key.

api_wallet_name
required
string non-empty

Name of the API wallet (included in the signing message).

key_name
string

Optional human-readable label for the API key.

valid_until
integer <int64> >= 1

Expiration timestamp (epoch ms). Must be ≤ 180 days from now. If omitted, defaults to 14 days from now.

required
object (EthereumSignature)

ECDSA signature (r, s) over the SHA-256 hash of the canonical JSON message. Verified with ecdsa.Verify(pubKey, hash, r, s).

The canonical message to sign is (keys alphabetically sorted, no whitespace): {"api_wallet_name":"<api_wallet_name>","api_wallet_public_key":"<public_key>","valid_until":<valid_until>}

Responses

Request samples

Content type
application/json
{
  • "ethereum_address": "string",
  • "public_key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  • "api_wallet_name": "dYdX",
  • "key_name": "my-trading-bot",
  • "valid_until": 1735689600000,
  • "signature": {
    }
}

Response samples

Content type
application/json
{
  • "api_key": "string",
  • "ethereum_address": "string",
  • "account_index": 10,
  • "key_name": "string",
  • "valid_until": 0,
  • "created_at": 0
}