x402 Protocol - ActumX

Overview

The x402 protocol enables machine-readable payment requirements using HTTP 402 (Payment Required). Clients can automatically discover pricing, settle payments, and retry requests without custom per-API billing logic.

x402 allows AI agents and automated systems to pay for API access programmatically. See the x402 Protocol concept for details.

Payment Flow

The x402 flow consists of three steps:

Request - Make initial request, receive 402 with payment details
Settle - Pay for the request using the settlement endpoint
Retry - Retry original request with payment proof

Get Protected Quote

A demonstration endpoint that requires payment via x402.

curl https://api.actumx.app/v1/protected/quote?topic=general \
  -H "x-api-key: actumx_live_abc123..."

Query Parameters

topic

string

Optional topic for the quote (default: “general”)

Request Headers (For Retry)

x-api-key

string

required

Your API key

x-payment-id

string

Payment ID from the 402 response

x-payment-proof

string

Receipt ID from the settlement response

Response (402 Payment Required)

When payment is required, you receive a 402 status with payment details:

error

string

Error code: “payment_required”

message

string

Human-readable message

x402

object

x402 protocol details

Show x402 object

version

string

Protocol version (“0.1-draft”)

paymentId

string

Unique payment identifier

amountCents

number

Cost in cents (25 cents = $0.25)

amountUsd

number

Cost in USD

currency

string

Currency code (“USD”)

endpoint

string

The endpoint being accessed

settlementEndpoint

string

Where to settle the payment

facilitator

string

Payment facilitator identifier

expiresAt

string

ISO 8601 expiration timestamp (10 minutes from creation)

{
  "error": "payment_required",
  "message": "This endpoint requires payment. Settle first and retry with payment proof.",
  "x402": {
    "version": "0.1-draft",
    "paymentId": "x402tx_xyz789",
    "amountCents": 25,
    "amountUsd": 0.25,
    "currency": "USD",
    "endpoint": "/v1/protected/quote",
    "settlementEndpoint": "/v1/x402/settle",
    "facilitator": "internal-simulator",
    "expiresAt": "2024-03-01T10:10:00Z"
  }
}

Response (200 Success)

After successful payment settlement:

data

object

Response data

Show data object

topic

string

Requested topic

insight

string

Information about x402

generatedAt

string

ISO 8601 timestamp

payment

object

Payment details

Show payment object

paymentId

string

Transaction ID

receiptId

string

Receipt ID

amountCents

number

Amount paid

status

string

Payment status (“completed”)

{
  "data": {
    "topic": "general",
    "insight": "x402 allows machine-readable payment requirements using HTTP 402 so clients can settle and retry without custom per-API billing logic.",
    "generatedAt": "2024-03-01T10:05:00Z"
  },
  "payment": {
    "paymentId": "x402tx_xyz789",
    "receiptId": "receipt_abc123",
    "amountCents": 25,
    "status": "completed"
  }
}

Settle Payment

Settle a payment for an x402 transaction by deducting credits from your account balance.

curl -X POST https://api.actumx.app/v1/x402/settle \
  -H "x-api-key: actumx_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "paymentId": "x402tx_xyz789"
  }'

Request Body

paymentId

string

required

Payment ID from the 402 response

Minimum length: 6 characters
Format: x402tx_[random_string]

Response

receiptId

string

Unique receipt identifier (use as payment proof)

paymentId

string

The payment ID that was settled

status

string

Payment status (“settled”)

amountCents

number

Amount deducted in cents

settledAt

string

ISO 8601 timestamp of settlement

{
  "receiptId": "receipt_abc123",
  "paymentId": "x402tx_xyz789",
  "status": "settled",
  "amountCents": 25,
  "settledAt": "2024-03-01T10:05:00Z"
}

Error Responses

Insufficient Balance (402)

{
  "error": "insufficient_balance",
  "requiredCents": 25,
  "balanceCents": 10,
  "message": "Top up balance in dashboard before settling this x402 payment."
}

Payment Not Found (404)

{
  "error": "payment_not_found"
}

If a payment is already settled, calling settle again returns the existing receipt details.

MCP Server (Model Context Protocol)

ActumX provides an MCP server that exposes agent wallet functionality through the Model Context Protocol.

MCP Endpoints

GET /mcp - Handle MCP discovery and initialize
POST /mcp - Handle MCP JSON-RPC requests

Initialize

curl -X POST https://api.actumx.app/mcp \
  -H "x-api-key: actumx_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
  }'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "actumx-mcp",
      "version": "0.1.0"
    }
  },
  "id": 1
}

List Tools

curl -X POST https://api.actumx.app/mcp \
  -H "x-api-key: actumx_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "wallet_balance",
        "title": "Wallet Balance",
        "description": "Return the selected agent wallet balance on Solana.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "agentId": {
              "type": "string",
              "description": "Optional agent id. If omitted, uses your most recent agent."
            }
          }
        }
      }
    ]
  },
  "id": 2
}

Call Tool

curl -X POST https://api.actumx.app/mcp \
  -H "x-api-key: actumx_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "wallet_balance",
      "arguments": {
        "agentId": "agent_abc123"
      }
    }
  }'

Response

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Agent My Agent (7xKzL3kQyH...) balance: 1.500000 SOL (1500000000 lamports)."
      }
    ],
    "structuredContent": {
      "agentId": "agent_abc123",
      "agentName": "My Agent",
      "publicKey": "7xKzL3kQyH...",
      "balanceLamports": 1500000000,
      "balanceSol": 1.5,
      "network": "solana",
      "error": null
    },
    "isError": false
  },
  "id": 3
}

JSON-RPC Error Codes

Code	Message	Description
-32001	API key required	Missing or invalid API key
-32600	Invalid Request	Malformed JSON-RPC request
-32601	Method not found	Unknown JSON-RPC method
-32602	Unknown tool	Tool name not recognized

Pricing

Current x402 endpoint pricing:

/v1/protected/quote: 25 cents per request

Payments are deducted from your account balance. Top up via the billing endpoint or dashboard.

Error Codes

Status	Error	Description
401	`missing_or_invalid_api_key`	API key required
402	`payment_required`	Payment needed (see x402 object)
402	`invalid_payment_proof`	Payment proof doesn’t match
402	`payment_not_settled`	Payment exists but not settled yet
402	`insufficient_balance`	Not enough credits to settle
404	`payment_not_found`	Payment ID doesn’t exist

Payment IDs expire 10 minutes after creation. If expired, make a new request to get a fresh payment ID.

Overview

Endpoints

​Overview

​Payment Flow

​Get Protected Quote

​Query Parameters

​Request Headers (For Retry)

​Response (402 Payment Required)

​Response (200 Success)

​Settle Payment

​Request Body

​Response

​Error Responses

​Insufficient Balance (402)

​Payment Not Found (404)

​MCP Server (Model Context Protocol)

​MCP Endpoints

​Initialize

​Response

​List Tools

​Response

​Call Tool

​Response

​JSON-RPC Error Codes

​Pricing

​Error Codes

Overview

Payment Flow

Get Protected Quote

Query Parameters

Request Headers (For Retry)

Response (402 Payment Required)

Response (200 Success)

Settle Payment

Request Body

Response

Error Responses

Insufficient Balance (402)

Payment Not Found (404)

MCP Server (Model Context Protocol)

MCP Endpoints

Initialize

Response

List Tools

Response

Call Tool

Response

JSON-RPC Error Codes

Pricing

Error Codes