Overview OKX.AI Wallet Payment Trade Market Exchange OS X Layer

A2MCP Integration Guide#

What is A2MCP?#

A2MCP (Agent-to-MCP) is a service type on OKX.AI through which ASPs provide standardized services that Agents can call. Services can be free or charge per call through x402.

A2MCP services fall into two categories based on endpoint type:

Endpoint type	Use case	Source of invocation information
MCP endpoint	Supports the MCP protocol and enables discovery and invocation of one or more Tools	Tool definitions returned by `tools/list`
HTTP endpoint	A regular HTTP API	The endpoint and the request method and parameter definitions provided by the ASP

Confirm that your service is suitable for integration#

Services suitable for A2MCP can usually be clearly expressed as “input parameters → clear results,” with invocation and delivery handled programmatically.

Characteristic	Description	Examples
Structured data or capabilities	Returns explicit results through an interface rather than purely manual processing	Weather, exchange rates, maps, market data, company information
Can be exposed as tools	Each capability can be broken down into a function with parameters	Order queries, invoice generation, translation
Verifiable results and relatively low risk	Return values are relatively deterministic	Query and read-only services
Ongoing value	Users may make repeated calls	Data APIs, industry knowledge bases, vertical search

Preparation before integration#

Follow the corresponding 4 steps based on how your service is implemented.

Complete service development, deployment, and testing before registration. During registration, the platform reads the information available from the endpoint and requests any necessary invocation inputs. Registration is allowed only after a successful test call. The platform does not develop or repair the service for you.

General requirements#

Provide a deployed, publicly accessible HTTPS endpoint with an address no longer than 512 characters. Do not use localhost, private-network, mock, or placeholder addresses, or redirect to localhost or private networks.
Calls with valid inputs must return complete business results consistent with the service description within 180 seconds.
Do not require users to provide sensitive credentials such as API keys, access tokens, private keys, or seed phrases. Configure third-party dependencies on the server side.

MCP

HTTP API

1
Build an MCP Server
Use an official MCP SDK to create a Server and register your business capabilities as Tools. If you already have a database, HTTP API, or SaaS service, you can call these capabilities from the Tool handler.
For guidance on building an MCP Server, see Build an MCP server.
Note on protocol versions and transports
Official tutorials and SDKs are continuously updated. Examples may use local stdio or different protocol versions. The OKX.AI integration workflow in this guide includes the initialize handshake. Choose an implementation that can negotiate a compatible protocol version with the platform.

Define tools and configure pricing

Define MCP Tools

Tool field	Purpose
name	Identifier used to invoke the tool programmatically
title	Service name displayed on the platform
description	Describes the service purpose, capabilities, and returned results
inputSchema	Defines parameter structure, types, required fields, and constraints

OKX.AI requires title and description to be non-empty. Each selected tool corresponds to one service, and multiple Services can share the same MCP Endpoint.

Configure pricing

Configure each tool’s x402 payment requirements on the server. The platform obtains pricing through invocation verification. Charge only for tools/call; initialize and tools/list must remain free.

Option 1: Free services

Return business results directly when the Tool is called. No x402 implementation is required.

Option 2: Pay-per-call services (x402)

Payment should be triggered at the tools/call stage. We recommend using the OKX Payment SDK: OKX provides server-side SDKs (@okxweb3/x402-* supports Node.js, Go, Rust, Java, and Python). Attach payment middleware to the endpoint and configure the recipient address, network, and price. The SDK handles 402 responses and onchain verification. For the full process, see Integrate through the SDK.

⚠️ x402 v2 payment challenges must be base64-encoded and placed in the PAYMENT-REQUIRED response header. The marketplace validates the response header, not the response body. Using the SDK is recommended to avoid errors in the challenge format or placement.

json

{
  "x402Version": 2,
  "resource": {
    "url": "https://<your-public-endpoint>/...",
    "description": "<service-description>",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:196",
      "asset": "0x779ded0c9e1022225f8e0630b35a9b54be713736",
      "amount": "10000",
      "payTo": "0x<your-x-layer-wallet>",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD₮0", "version": "1" }
    }
  ]
}

Paid endpoints should validate required parameters before returning payment requirements, to avoid users paying for invalid requests. The network, payment scheme, asset, token name and version, amount, and recipient address in the payment challenge must be complete. The actual amount must match the price parsed by the platform.

3
Deploy and verify the MCP service
After deployment, use the official MCP Inspector or a compatible MCP Client to connect to the public HTTPS MCP address, such as https://your-domain.example/mcp, and verify the following workflow:
text
Client initialize → Server returns the initialization result → Client notifications/initialized → tools/list retrieves tool definitions → tools/call invokes the specified tool with valid arguments
4
Register on OKX.AI
Submit the Endpoint following the ASP registration process.

1
Build an HTTP API
Provide a business API that can be called through GET or POST. If you already have an API, skip this step. If developing from scratch, refer to the official FastAPI tutorial or use a Web framework you are familiar with.
Databases, internal systems, and SaaS services can all serve as server-side sources of data and capabilities, but internal addresses cannot be used directly as external Endpoints.

Prepare invocation information and configure pricing

Information	Preparation requirement
Service name	A name that users can understand
Service description	Describe the service purpose, capabilities, and returned results
Request method	GET or POST, consistent with the actual API
Input parameter format	Specify each parameter's name, type, meaning, and whether it is required; if there are no parameters, state “No parameters”

Parameter types include string, number, boolean, array, and object. Describe the contents of objects and arrays. For example: city (string, required): Name of the city to query.

Registration does not additionally require a complete cURL command, default values or example values for every parameter, location, or hand-written Schema JSON. Provide valid business inputs needed for verification as prompted by the Agent.

Configure pricing

After completing the call definitions, choose free or pay-per-call:

Option 1: Free services

Return business results directly when the API is called (HTTP 200). No x402 implementation is required.

Option 2: Pay-per-call services (x402)

The price comes from the endpoint's x402 settings. We recommend using the OKX Payment SDK: OKX provides server-side SDKs (@okxweb3/x402-* supports Node.js, Go, Rust, Java, and Python). Attach payment middleware to the endpoint and configure the recipient address, network, and price. The SDK handles 402 responses and onchain verification. For the full process, see Integrate through the SDK.

⚠️ x402 v2 payment challenges must be base64-encoded and placed in the PAYMENT-REQUIRED response header. The marketplace validates the response header, not the response body. Using the SDK is recommended to avoid errors in the challenge format or placement.

json

{
  "x402Version": 2,
  "resource": {
    "url": "https://<your-public-endpoint>/...",
    "description": "<service-description>",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:196",
      "asset": "0x779ded0c9e1022225f8e0630b35a9b54be713736",
      "amount": "10000",
      "payTo": "0x<your-x-layer-wallet>",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD₮0", "version": "1" }
    }
  ]
}

3
Deploy and verify the HTTP API
Deploy the HTTP API and configure HTTPS for the domain. Ensure that third-party dependencies, network access, and server-side credentials are configured.
Use curl or an equivalent client to call the public HTTPS business route with the actual request method and valid parameters, and check the response and business results. The following shows only the structure of a POST JSON request. Replace the API and inputs with your own:
bash
curl -i -X POST 'https://your-domain.example/api/weather' \ -H 'Content-Type: application/json' \ -d '{"city":"Shanghai"}'
For paid services, also check the x402 payment requirements when no payment has been made, and complete delivery when the request is replayed with valid payment proof.
4
Register on OKX.AI
Submit the Endpoint following the ASP registration process.

Table of contents

What is A2MCP?

Confirm that your service is suitable for integration

Preparation before integration

General requirements