Quickstart#

Exchange OS Open API provides unified REST, WebSocket, and transaction-signing capabilities for Perps and Spot. This guide uses the Python SDK to cover credential setup, market queries, and transaction submission.

If you have not registered an OKX CEX account yet, please go to https://www.okx.com/account/register to sign up and complete KYC verification.

Step 1: Create an API Key#

Create an API Key in the OKX CEX API management page https://www.okx.com/okx-api or OKX App, and securely store:

• API Key
• Secret Key
• Passphrase In the OKX App, go to Assets > Onchain > menu > API Setup Guide to configure an API Key and bind an EOA Agent. Enable the permissions required for Onchain Perps and Spot. Private REST requests and private WebSocket subscriptions require an API Key, Secret Key, and Passphrase. Public REST requests and public WebSocket subscriptions do not require credentials.

The API Key must have Onchain permissions enabled for Prediction, Perps, and Spot.


Private REST requests require the API Key, Secret Key, and Passphrase. Public REST requests do not require credentials.

Step 2: Authorize an Agent#

1. In the OKX App, go to API Setup Guide, bind your EOA wallet, authorize the Agent, and ensure its status is active and the authorization has not expired.
2. Save the Agent address and private key securely.

The Agent private key is used locally for EIP-712 transaction signing and is never sent to the server. Read-only requests do not require the Agent private key.

Step 3: Install the Python SDK#

The Python SDK requires Python 3.10 or later.

python -m pip install exchangeos-sdk

For a source checkout with Notebook support:

python -m pip install -e '.[notebook]'

For local development, tests, and Notebooks:

python -m pip install -e '.[test,notebook]'

The SDK includes REST and WebSocket clients, REST authentication, and local MessagePack and EIP-712 transaction signing.

Step 4: Configure Environment Variables#

export EXCHANGEOS_API_KEY="your-api-key"
export EXCHANGEOS_API_SECRET="your-api-secret"
export EXCHANGEOS_API_PASSPHRASE="your-passphrase"
export EXCHANGEOS_ASSET_ID="your-asset-id"

# Required only when creating or submitting signed transactions
export EXCHANGEOS_AGENT_PRIVATE_KEY="your-authorized-agent-private-key"

Use a secrets-management service in production. Never commit credentials, private keys, .env files, or Notebook outputs containing account data to a repository.

Step 5: Initialize the Client#

The SDK connects to the Production environment by default. Public market-data requests do not require credentials:

from exchangeos_sdk import ExchangeOSClient, RestMarketType

with ExchangeOSClient() as client:
    instruments = client.market.instruments(
        market_type=RestMarketType.PERP
    )
    tickers = client.market.tickers(
        market_type=RestMarketType.PERP
    )
    print({"instruments": len(instruments), "tickers": len(tickers)})

Private REST, private WebSocket, and transaction submission require API credentials:

import os

from exchangeos_sdk import Credentials, ExchangeOSClient

credentials = Credentials(
    api_key=os.environ["EXCHANGEOS_API_KEY"],
    secret_key=os.environ["EXCHANGEOS_API_SECRET"],
    passphrase=os.environ["EXCHANGEOS_API_PASSPHRASE"],
)

with ExchangeOSClient(auth=credentials) as client:
    balance = client.account.balance()
    print(balance)

Use RestMarketType for REST query arguments. Use MarketType or the appropriate transaction builder when constructing a signed action. The SDK submits signed Spot and Perps actions only.

Step 6: Query Tradable Products#

from exchangeos_sdk import ExchangeOSClient, RestMarketType

with ExchangeOSClient() as client:
    instruments = client.market.instruments(
        market_type=RestMarketType.PERP
    )

    for instrument in instruments:
        print(instrument)

Submit orders only for products whose state is live. Validate prices and quantities against the product’s returned precision, minimum size, and other trading limits.

Step 7: Create, Sign, and Submit a Transaction#

Write operations require an authorized Agent private key to generate an EIP-712 signature locally. When client_order_id is omitted, order_item() generates a valid API clientOrderId.

import os

from exchangeos_sdk import (
    Credentials,
    ExchangeOSClient,
    MarginMode,
    OrderSide,
    OrderTimeInForce,
    PlaceOrder,
    limit_order_type,
    order_item,
    perp_market,
)

credentials = Credentials(
    api_key=os.environ["EXCHANGEOS_API_KEY"],
    secret_key=os.environ["EXCHANGEOS_API_SECRET"],
    passphrase=os.environ["EXCHANGEOS_API_PASSPHRASE"],
)

order = order_item(
    asset_id=os.environ["EXCHANGEOS_ASSET_ID"],
    side=OrderSide.BUY,
    market_type=perp_market(MarginMode.CROSS),
    price=os.getenv("EXCHANGEOS_ORDER_PRICE", "50000"),
    size=os.getenv("EXCHANGEOS_ORDER_SIZE", "0.001"),
    order_type=limit_order_type(OrderTimeInForce.GTC),
)

action = PlaceOrder(orders=[order])

with ExchangeOSClient(auth=credentials) as client:
    signed_transaction = client.sign_action(
        action,
        os.environ["EXCHANGEOS_AGENT_PRIVATE_KEY"],
    )
    result = client.trade.place_order(signed_transaction)

print({
    "clientOrderId": order["clientOrderId"],
    "response": result,
})

The SDK does not automatically retry signed write operations. If a transaction receipt is temporarily unavailable, query the final order or transaction state instead of submitting the same transaction again.

Step 8: Query Orders, Account Data, and Transaction Results#

GET /api/v5/exchangeos/trade/orders-pending
GET /api/v5/exchangeos/trade/orders-history
GET /api/v5/exchangeos/trade/order
GET /api/v5/exchangeos/trade/fills
GET /api/v5/exchangeos/account/balance
GET /api/v5/exchangeos/account/positions
GET /api/v5/exchangeos/trade/transaction

Use txHash, oid, clientOrderId, or pagination cursors to retrieve the final status of transactions and orders.