Tema

Agent API - One-time Payment#

The Buyer's wallet pays the Seller's wallet directly via transferWithAuthorization (EIP-3009) — a single immediate on-chain transfer per payment.

Base URL: https://web3.okx.com
Path prefix: /api/v6/pay/a2a
Intent: charge
Method: evm
Network: X Layer (chainId: 196)

Authentication#

Authentication for the Agent service is per-endpoint:

Endpoint	Authentication
`POST /api/v6/pay/a2a/payment/create`	Required: API Key (`OK-ACCESS-*` headers) or OnchainOS internal call
`GET /api/v6/pay/a2a/p/{paymentId}`	Public — no authentication required
`POST /api/v6/pay/a2a/p/{paymentId}/credential`	Public — no authentication required
`GET /api/v6/pay/a2a/p/{paymentId}/status`	Public — no authentication required

The Buyer-side endpoints (fetch detail, submit credential, query status) are publicly accessible because the Buyer does not hold the Seller's API Key. Smart-Account internally relies on paymentId and the matching challenge to validate request legitimacy.

API Key authentication uses the following request headers:

Header	Required	Description
`OK-ACCESS-KEY`	Yes	API Key
`OK-ACCESS-SIGN`	Yes	Request signature
`OK-ACCESS-PASSPHRASE`	Yes	API passphrase
`OK-ACCESS-TIMESTAMP`	Yes	ISO 8601 timestamp
`Content-Type`	Yes	Set to `application/json` for POST requests

All responses use a uniform business envelope:

json

{
  "code": "0",
  "msg": "success",
  "data": { /* business fields */ }
}

On business errors, code is non-"0" and data is null. See the Error codes section at the bottom for the full list.

1. /api/v6/pay/a2a/payment/create#

POST

/api/v6/pay/a2a/payment/create

Called by the Seller Agent to create a Charge payment request and obtain the payment deliverables.

Request parameters#

Parameter	Type	Required	Description
`type`	`String`	Yes	Fixed `"charge"`
`amount`	`String`	Yes	Amount (denomination decimal string, e.g. `"0.1"`)
`symbol`	`String`	Yes	Token symbol, e.g. `"USD₮0"` / `"USDC"` / `"USDG"`
`recipient`	`String`	Yes	Seller recipient wallet address
`description`	`String`	No	Payment description
`externalId`	`String`	No	Seller-side business ID, used for idempotency
`expiresIn`	`Integer`	No	Payment validity (seconds), default `1800`
`realm`	`String`	No	Business realm; defaults to the realm bound to the Seller at registration
`deliveries`	`Object`	No	Delivery toggles
`deliveries.includeUrl`	`Boolean`	No	Default `true`; generate the payment URL. Phase 1 supports URL deliveries only

The create request uses symbol + decimal amount. The server converts these in the response to the standard MPP challenge (with atomic-unit amount and contract address currency) for the Buyer to sign. In phase 1, deliveries only supports the URL type — QR code, card, and other delivery formats are not yet supported.

Request example#

bash

curl --location --request POST 'https://web3.okx.com/api/v6/pay/a2a/payment/create' \
--header 'Content-Type: application/json' \
--header 'OK-ACCESS-KEY: 37c541a1-****-****-****-10fe7a038418' \
--header 'OK-ACCESS-SIGN: leaV********3uw=' \
--header 'OK-ACCESS-PASSPHRASE: 1****6' \
--header 'OK-ACCESS-TIMESTAMP: 2023-10-18T12:21:41.274Z' \
--data '{
  "type": "charge",
  "amount": "0.1",
  "symbol": "USD₮0",
  "recipient": "0xSellerWalletAddress",
  "description": "Task #5678 direct payment",
  "externalId": "task-5678",
  "expiresIn": 1800,
  "realm": "provider.example.com",
  "deliveries": {
    "includeUrl": true
  }
}'

Response parameters#

Parameter	Type	Description
`paymentId`	`String`	Payment ID, format `a2a_<base58(uuidv7)>`
`status`	`String`	Initial value fixed at `"pending"`
`createdAt`	`String`	Creation time, RFC 3339
`expiresAt`	`String`	Expiration time, RFC 3339
`challenge`	`Object`	MPP challenge structure. See Challenge
`deliveries`	`Array<Delivery>`	List of deliveries. See Delivery

Response example#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "paymentId": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
    "status": "pending",
    "createdAt": "2026-04-21T10:00:00Z",
    "expiresAt": "2026-04-21T10:30:00Z",
    "challenge": {
      "type": "payment-challenge",
      "data": {
        "id": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
        "realm": "provider.example.com",
        "method": "evm",
        "intent": "charge",
        "request": {
          "amount": "100000",
          "currency": "0x779ded0c9e1022225f8e0630b35a9b54be713736",
          "recipient": "0xSellerWalletAddress",
          "description": "Task #5678 direct payment",
          "externalId": "task-5678",
          "methodDetails": {
            "chainId": 196,
            "authorizationType": "eip-3009"
          }
        },
        "expires": "2026-04-21T10:30:00Z"
      }
    },
    "deliveries": [
      { "type": "url", "value": "https://pay.okx.com/p/a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB", "description": "Universal payment link" }
    ]
  }
}

2. `/api/v6/pay/a2a/p/{paymentId}`#

GET

/api/v6/pay/a2a/p/{paymentId}

The Buyer Agent fetches the full challenge by paymentId. The same URL returns the HTML payment page when accessed in a browser, and returns this JSON when called with an A2A Pay UA or Accept: application/json.

Request parameters#

Parameter	Location	Type	Required	Description
`paymentId`	path	`String`	Yes	Payment ID

Response parameters#

Parameter	Type	Description
`paymentId`	`String`	Payment ID
`status`	`String`	Current status (see Status dictionary)
`createdAt`	`String`	Creation time
`expiresAt`	`String`	Expiration time
`challenge`	`Object`	MPP challenge structure (same as create)

Response example#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "paymentId": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
    "status": "pending",
    "createdAt": "2026-04-21T10:00:00Z",
    "expiresAt": "2026-04-21T10:30:00Z",
    "challenge": { "type": "payment-challenge", "data": { "...same as create response..." } }
  }
}

3. `/api/v6/pay/a2a/p/{paymentId}/credential`#

POST

/api/v6/pay/a2a/p/{paymentId}/credential

The Buyer Agent submits the credential after completing the EIP-3009 signature. Once Smart-Account verifies the signature, it broadcasts the on-chain transaction on the Buyer's behalf.

The request body only contains payload; the challenge is not echoed back — the server looks up its stored challenge by paymentId and validates it against the supplied payload.authorization.

Request parameters#

Parameter	Location	Type	Required	Description
`paymentId`	path	`String`	Yes	Payment ID
`payload`	body	`Object`	Yes	Signature data
`payload.type`	body	`String`	Yes	Fixed `"transaction"`
`payload.signature`	body	`String`	Yes	EIP-712 signature (65 bytes, 0x-prefixed)
`payload.authorization`	body	`Object`	Yes	EIP-3009 authorization parameters. See Authorization

Request example#

bash

curl --location --request POST 'https://web3.okx.com/api/v6/pay/a2a/p/a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB/credential' \
--header 'Content-Type: application/json' \
--data '{
  "payload": {
    "type": "transaction",
    "signature": "0xabcdef...01",
    "authorization": {
      "type": "eip-3009",
      "from": "0xBuyerWalletAddress",
      "to": "0xSellerWalletAddress",
      "value": "100000",
      "validAfter": "0",
      "validBefore": "1714521600",
      "nonce": "0xf374661b1c7d5e7a8b3e2f1a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c"
    }
  }
}'

Response parameters#

Parameter	Type	Description
`paymentId`	`String`	Payment ID
`status`	`String`	Becomes `"settling"` after validation passes
`acceptedAt`	`String`	Time the credential was accepted
`trackingUrl`	`String`	Status tracking page URL

Response example#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "paymentId": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
    "status": "settling",
    "acceptedAt": "2026-04-21T10:05:00Z",
    "trackingUrl": "https://pay.okx.com/status/a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB"
  }
}

4. `/api/v6/pay/a2a/p/{paymentId}/status`#

GET

/api/v6/pay/a2a/p/{paymentId}/status

Query payment status. After the Buyer submits the credential, both the Seller and Buyer poll this endpoint for the settlement result.

Request parameters#

Parameter	Location	Type	Required	Description
`paymentId`	path	`String`	Yes	Payment ID

Response parameters#

Parameter	Type	Description
`paymentId`	`String`	Payment ID
`status`	`String`	Current status (see Status dictionary)
`executed`	`Object`	Returned only when `status = completed`
`executed.txHash`	`String`	On-chain transaction hash
`executed.blockNumber`	`Integer`	Block height
`executed.blockTimestamp`	`String`	Block time, RFC 3339
`fee`	`Object`	Platform fee (if any)
`fee.amount`	`String`	Platform fee amount (atomic units)
`fee.bps`	`Integer`	Fee rate in basis points (1 bps = 0.01%)
`failure`	`Object`	Returned only when `status = failed`
`failure.reason`	`String`	Machine-readable failure reason
`failure.message`	`String`	Human-readable failure explanation

Response example — settled#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "paymentId": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
    "status": "completed",
    "executed": {
      "txHash": "0xabc...123",
      "blockNumber": 12345678,
      "blockTimestamp": "2026-04-21T10:05:15Z"
    },
    "fee": { "amount": "300", "bps": 30 }
  }
}

Response example — in progress#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "paymentId": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
    "status": "settling"
  }
}

Response example — failed#

json

{
  "code": "0",
  "msg": "success",
  "data": {
    "paymentId": "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB",
    "status": "failed",
    "failure": {
      "reason": "transaction_reverted",
      "message": "EIP-3009 transferWithAuthorization reverted on chain"
    }
  }
}

Shared data structures#

Challenge#

Parameter	Type	Required	Description
`type`	`String`	Yes	Fixed `"payment-challenge"`
`data`	`Object`	Yes	Business fields
`data.id`	`String`	Yes	Equal to `paymentId`
`data.realm`	`String`	Yes	Business realm
`data.method`	`String`	Yes	Fixed `"evm"`
`data.intent`	`String`	Yes	Fixed `"charge"`
`data.request`	`Object`	Yes	Payment request fields
`data.request.amount`	`String`	Yes	Amount (atomic-unit string)
`data.request.currency`	`String`	Yes	ERC-20 contract address
`data.request.recipient`	`String`	Yes	Seller recipient wallet address
`data.request.description`	`String`	No	Payment description
`data.request.externalId`	`String`	No	Seller business ID
`data.request.methodDetails.chainId`	`Integer`	Yes	EVM chainId (X Layer is `196`)
`data.request.methodDetails.authorizationType`	`String`	Yes	Fixed `"eip-3009"` for Charge
`data.expires`	`String`	Yes	Short-lived challenge expiration time, RFC 3339

Authorization#

Parameter	Type	Required	Description
`type`	`String`	Yes	Fixed `"eip-3009"`
`from`	`String`	Yes	Buyer wallet address (payer identity is recovered from this field via ECDSA)
`to`	`String`	Yes	Recipient wallet address
`value`	`String`	Yes	Amount (atomic units)
`validAfter`	`String`	Yes	Validity start timestamp (Unix seconds)
`validBefore`	`String`	Yes	Expiration timestamp (Unix seconds)
`nonce`	`String`	Yes	32-byte random nonce (0x-prefixed hex)

Additional constraints: payload.authorization.to must exactly equal the challenge's request.recipient; payload.authorization.value must equal request.amount. Otherwise signature verification fails.

Delivery#

Parameter	Type	Required	Description
`type`	`String`	Yes	Fixed `"url"` in phase 1
`value`	`String`	Yes	Payment link, format `https://pay.okx.com/p/{paymentId}`
`description`	`String`	No	Description

Status dictionary#

Status	Meaning
`pending`	Created, waiting for the Buyer to submit a credential
`settling`	Credential received; Smart-Account is broadcasting the on-chain transaction
`completed`	On-chain confirmed; funds received
`failed`	Signature verification failed / on-chain revert / simulation failure
`expired`	Expired

Payment ID format#

paymentId = "a2a_" + base58(uuidv7)
example   = "a2a_01HZX8Q9RK3JWYV7M2N5T8P4AB"

Error codes#

Error responses use the uniform envelope {"code": "<code>", "msg": "<message>", "data": null}.

1. Authentication errors (HTTP 401, only for `payment/create`)#

Code	Description
50103	Header `OK-ACCESS-KEY` cannot be empty
50104	Header `OK-ACCESS-PASSPHRASE` cannot be empty
50105	Header `OK-ACCESS-PASSPHRASE` is incorrect
50106	Header `OK-ACCESS-SIGN` cannot be empty
50107	Header `OK-ACCESS-TIMESTAMP` cannot be empty
50111	Invalid `OK-ACCESS-KEY`
50112	Invalid `OK-ACCESS-TIMESTAMP`
50113	Invalid signature

2. Request errors#

Code	HTTP status	Description
50011	429	Request rate exceeds the limit allowed for this endpoint
50014	400	Required parameter `{param}` cannot be empty

3. Generic business errors#

Code	HTTP status	Description
50026	500	System error, please retry later
81001	200	Invalid `{param}` parameter
81004	200	Unsupported chain
80007	200	Risky address

4. MPP business errors#

Code	Identifier	Description
70000	`invalid_params`	Parameter validation failed
70001	`unsupported_chain`	Unsupported chain / chainId
70002	`payer_blocked`	Payer address blocked by risk control
70003	`invalid_credential`	Credential mismatch with stored data / validation failure
70004	`invalid_signature`	EIP-712 / EIP-3009 signature is invalid