AI Builder Program Integration Guide

1. What Is the AI Builder Program?

The OKX AI Builder Program is designed for builders of AI Agents, trading assistants, automated strategies, and developer tools. Once you join the program, you will receive a unique Builder Code. When users execute eligible trades through ATK within your product, ATK writes the Builder Code to the order attribution field. OKX uses this information to track trading activity and calculate rebates.The AI Builder Code identifies the source of a trade and maps to an OKX Broker Code at the underlying layer. In ATK's MCP and CLI, the corresponding technical parameter is aiBuilderCode. It is not an API Key and cannot be used to access user accounts.

2. Choose the Right Integration Method

This guide focuses on local MCP and CLI integration. If your product trades on behalf of multiple users from a third-party server, refer directly to the third-party server integration section. Do not ask users to send their API Secret to your Agent, web frontend, or large language model.

3. Prerequisites

Before you begin, prepare the following:

• An OKX account that can use the relevant trading products;

• Node.js 18 or later;

• An AI client that supports MCP, or a local environment capable of running the CLI;

• The Builder Code issued after your AI Builder application is approved;

• A Demo Trading API Key for integration testing, or a live trading API Key for production.

We recommend enabling only the following permissions for the API Key:

• Read: Query account information, positions, and orders;

• Trade: Place, amend, or cancel orders;

• Withdraw is neither required nor recommended.

Use Demo Trading for your initial integration. Once you have verified trade attribution, gradually move to live trading with small amounts.

4. Apply for AI Builder

1. Sign in to OKX and go to the AI Builder Program page.

2. Click “Apply Now” and select AI Builder as the application type.

3. Enter the applicant and project information, including the project name, project link, and project overview.

4. Read and accept the applicable Terms of Service, then submit your application.

5. Obtain your Builder Code, integration materials, and testing resources from the AI Builder Dashboard or your application approval notice.

If your Builder Code is shown as “Under Review” or “Inactive,” you may proceed with technical integration testing, but the relevant trades will not generate rebates. Eligible trades will begin to count toward rebates only after the status changes to “Activated.”

5. Install and Configure ATK

Install the latest versions of the MCP Server and CLI:

npm install -g @okx_ai/okx-trade-mcp @okx_ai/okx-trade-cli

Confirm that the installation was successful:

okx --version
okx-trade-mcp --version

Use the interactive wizard to configure the OKX site, demo or live trading environment, and API credentials:okx config initBy default, credentials are stored locally on the user's device at ~/.okx/config.toml.

Do not commit this file to a code repository or include credentials in prompts, Skill text, web frontends, or logs.

6. Integrate via MCP

6.1 Configure the MCP Client Automatically

To configure MCP, users need to run one of the following commands in a terminal:

okx-trade-mcp setup --client claude-desktop
okx-trade-mcp setup --client cursor
okx-trade-mcp setup --client claude-code
okx-trade-mcp setup --client vscode

For initial integration testing, load only the required modules, such as market data, account, and spot trading:

okx-trade-mcp setup \
--client cursor \
--profile demo \
--modules market,account,spot

6.2 Pass aiBuilderCode

When calling MCP tools that place orders or execute strategy trades, pass aiBuilderCode in the tool parameters. The following is an example of the parameter format:

{
"instId": "BTC-USDT",
"tdMode": "cash",
"side": "buy",
"ordType": "limit",
"sz": "<SIZE>",
"px": "<PRICE>",
"aiBuilderCode": "<YOUR_BUILDER_CODE>"
}

aiBuilderCode is the parameter name provided by ATK for MCP and CLI. ATK converts it into the Builder Code required for order attribution; there is no need to use brokerCode instead in MCP/CLI calls. Ensure that the same aiBuilderCode is passed in every tool call that can generate a trade to prevent some orders from missing attribution.

6.3 Validate in Stages

We recommend completing the following tests in order:

1. Query the latest BTC-USDT price to validate the unauthenticated market data functionality;

2. Query the demo trading account balance to validate the API credentials;

3. Check the account and positions in read-only mode;

4. Preview the order parameters in demo trading;

5. After user confirmation, submit a small demo order;

6. Query the order status and verify the trade attribution in the AI Builder Dashboard.

During the initial rollout, you can use --read-only to disable all write operations:

okx-trade-mcp \
--profile demo \
--modules market,account,spot \
--read-only

7. Integrate via CLI

The CLI is suitable for local scripts, Agent Skills, and automated workflows. Every CLI command that generates a trade must include --aiBuilderCode. We recommend appending this parameter consistently in your code or wrapper to prevent the Agent from omitting it. AI_BUILDER_CODE="<YOUR_BUILDER_CODE>"

First, validate the market data and account connections: okx market ticker BTC-USDT
okx account balanceThen submit a test order in demo trading. The parameters below are formatting examples only. Replace them with values that comply with current market rules and your test plan:

okx spot place \
--instId BTC-USDT \
--side buy \
--ordType limit \
--sz <SIZE> \
--px <PRICE> \
--aiBuilderCode "$AI_BUILDER_CODE"You can also pass the Builder Code directly in a single CLI call:okx spot place \
--instId BTC-USDT \
--side buy \
--ordType limit \
--sz <SIZE> \
--px <PRICE> \
--aiBuilderCode <YOUR_BUILDER_CODE>

If you are publishing an Agent Skill or Plugin, we recommend using one of the following approaches:

• Append --aiBuilderCode to every trading command in the Skill or Plugin's centralized invocation layer;

• Provide a wrapper with a fixed internal Builder Code and have the Agent call only that wrapper;

• Cover every order placement, order amendment, order cancellation, and strategy trading path in your tests to ensure none bypass the centralized attribution entry point.

Do not rely solely on natural-language instructions telling the Agent to “remember to add the Builder Code.” Prompts may be overlooked, so aiBuilderCode should be passed consistently by the code or wrapper.

8. Third-Party Server Integration

If your service runs in the cloud and accesses accounts or executes trades on behalf of multiple users, do not reuse the credential model designed for local MCP/CLI integrations. We recommend applying for OAuth Broker and integrating with Fast API:

1. The user is redirected from your product to the OKX authorization page;

2. The user signs in and confirms authorization on the OKX page;

3. Your server completes the OAuth and Fast API flows;

4. User credentials are generated and managed according to the Broker security model and bound to trusted server IPs;

5. Your server includes your Broker Code when placing orders to complete trade attribution.

9. Verify Trade Attribution

Do not treat “order successfully placed,” “order filled,” “trade attribution,” and “rebate settlement” as the same status. Before going live, verify each of the following:

• You are using an ATK version that supports AI Builder attribution;

• The Builder Code is active and matches your project;

• The correct aiBuilderCode is included in MCP or CLI trading calls;

• Demo and live trading profiles have not been mixed up;

• The test order was successfully submitted and produced the expected result;

• The corresponding attribution data is visible in the AI Builder Dashboard;

• The rebate details comply with your current Broker tier and the applicable rules.

If an order succeeds but no attribution data appears in the Dashboard, stop increasing trading volume and check the ATK version, Builder Code status, aiBuilderCode parameter, and order path. Until the attribution issue is resolved, do not assume that missing attribution can be backfilled automatically later.

10. Rebate Information

Eligible Builders may receive rebates based on their Broker tier and the applicable rules, with rates of up to 50%. Actual eligibility, rebate rates, applicable products, calculation periods, and settlement amounts are subject to the AI Builder Dashboard, the latest Broker rules, and your partnership agreement.The following situations may cause a trade to be excluded from rebates:

• The Builder Code has not been activated or is invalid, or aiBuilderCode was not passed correctly;

• The user, account, region, trading product, or fee rate does not meet the applicable requirements;

• The trade involves self-rebating, abnormal trading, or other behavior that does not comply with the program rules;

• The order was not filled or did not generate net fees eligible for rebates.

Integrating ATK does not guarantee rebates or any trading returns. Do not represent “up to 50%” as meaning that every Builder or every trade will receive a 50% rebate. For the latest rules, see the OKX Broker Rules.

11. Security and Go-Live Checklist

• Start in demo trading and use small trade amounts when first moving to live trading;

• Use least-privilege API Keys and do not enable withdrawal permissions;

• Bind API Keys to trusted IP addresses where applicable;

• Do not expose credentials in prompts, browser frontends, code repositories, screenshots, or logs;

• Set limits on trade amounts, frequency, leverage, products, and trading pairs;

• Require explicit user confirmation for live order placement, order cancellation, leverage changes, and strategy activation;

• If a request times out or returns an unknown status, query the order status before placing the order again;

• Log order IDs, request trace IDs, and error codes, but do not log secrets;

• Regularly reconcile expected trading volume, actual attributed volume, and rebate details.

AI may produce unintended trades because of model errors, hallucinations, latency, market volatility, slippage, liquidity conditions, or technical failures. ATK does not provide investment advice or guarantee profits. You and your end users must independently verify information, supervise automated strategies, and remain responsible for trading decisions.

12. Frequently Asked Questions

Should I choose MCP or CLI?

Choose MCP when you need an AI client to access trading capabilities through standardized tool calls. Choose CLI when you need to execute commands directly in scripts, Skills, or automated tasks. Both can be used together, but each order can only be attributed according to the Builder Code that ultimately takes effect.

What is the difference between Builder Code, aiBuilderCode, and an API Key?

Builder Code is the business identifier used for trade attribution and rebate calculations. aiBuilderCode is the parameter name used to carry that identifier in MCP and CLI calls. For direct OpenAPI integrations, write the Broker Code to the order tag as specified in the Broker documentation. An API Key provides access to a specific user's account; it cannot be replaced by a Builder Code and must not be disclosed.

Do trades made while my application is under review generate rebates?

No. You can perform integration testing during the review period, but only eligible trades made after the Builder Code has been activated will begin to count toward rebates.

Why was my order successful, but no rebate is visible?

Common reasons include an inactive Builder Code, an ATK version that does not support aiBuilderCode, a missing or incorrect aiBuilderCode parameter in the trading call, an unfilled trade, an ineligible trade, or Dashboard data that is still being updated. Verify trade attribution first, then check rebate settlement.