快速开始#

Exchange OS Open API 为 Perps 与 Spot 提供统一的 REST、WebSocket 和交易签名能力。以下以 Python SDK 说明从创建凭证到查询市场及提交交易的基本流程。

若没有注册过 OKX CEX 账户，请先至 https://www.okx.com/account/register 注册账号并完成 KYC

第 1 步：创建 API Key#

在 OKX CEX API管理页面 https://www.okx.com/okx-api 或 OKX App 创建 API Key 在 OKX App 的「资产（Assets）」页面，选择「链上（Onchain）」，点击右上角菜单，进入「API Setup Guide」，即可设置 API Key 并绑定 EOA Agent。

API Key
Secret Key
Passphrase

在 OKX App 中，依次进入资产（Assets）> 链上（Onchain）> 右上角菜单 > API Setup Guide，即可设置 API Key 并绑定 EOA Agent。

API Key 需要启用 Onchain 权限，才可使用Perps 与 Spot 。私有 REST 请求和私有 WebSocket 订阅需要 API Key、Secret Key 与 Passphrase。公开 REST 请求和公开 WebSocket 订阅无需凭证。

API Key 必须启用链上（Onchain）权限，涵盖 prediction、perp 与 spot。

![image](../../images/API permission-4.png)

第 2 步：授权 Agent#

在 OKX App 的「API Setup Guide」，绑定 EOA 钱包，授权 Agent，并确认状态为 active 且未过期。
保存 Agent 地址与私钥

Agent 私钥仅在本地用于 EIP-712 交易签名，不会发送至服务器。只读请求不需要 Agent 私钥。

第 3 步：安装 Python SDK#

Python SDK 需要 Python 3.10 或更高版本。

bash

python -m pip install exchangeos-sdk

如从源码检出并需运行 Notebook，请使用：

bash

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

如需进行本地开发、测试及运行 Notebook：

bash

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

SDK 包含 REST Client、WebSocket Client、REST 认证、本地 MessagePack 和 EIP-712 交易签名能力。

第 4 步：配置环境变量#

bash

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"

# 仅在创建或提交已签名交易时需要
export EXCHANGEOS_AGENT_PRIVATE_KEY="your-authorized-agent-private-key"

生产环境应使用密钥管理服务。不要将凭证、私钥、.env 文件或包含账户数据的 Notebook 输出提交到代码仓库。

第 5 步：初始化 Client#

SDK 默认连接 Production 环境。公开市场数据无需传入凭证：

python

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)})

私有 REST、私有 WebSocket 和交易提交需配置 API 凭证：

python

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)

RestMarketType 仅用于 REST 查询参数；构造已签名交易时，使用 MarketType 或对应的交易建构器。SDK 仅提交 Spot 与 Perps 的已签名交易。

第 6 步：查询可交易产品#

python

from exchangeos_sdk import ExchangeOSClient, RestMarketType

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

    for instrument in instruments:
        print(instrument)

仅对状态为 live 的产品提交交易，并使用产品返回的精度、最小交易数量及其他交易限制校验价格和数量。

第 7 步：创建、签名并提交交易#

写操作需要已授权 Agent 的私钥，在本地完成 EIP-712 签名。order_item() 未传入 client_order_id 时，会自动生成有效的 API clientOrderId。

python

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,
})

SDK 不会自动重试已签名写操作。若暂时无法取得交易回执，请查询订单或交易最终状态，不要重复提交相同交易。

第 8 步：查询订单、账户和交易结果#

http

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

可使用 txHash、oid、clientOrderId 或分页游标查询订单和交易的最终状态。