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..."

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

// Step 1: Initial request (will get 402)
const response1 = await fetch('https://api.actumx.app/v1/protected/quote?topic=general', {
  headers: {
    'x-api-key': 'actumx_live_abc123...'
  }
});
const payment = await response1.json();

// Step 2: Settle payment
const response2 = await fetch('https://api.actumx.app/v1/x402/settle', {
  method: 'POST',
  headers: {
    'x-api-key': 'actumx_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ paymentId: payment.x402.paymentId })
});
const settlement = await response2.json();

// Step 3: Retry with proof
const response3 = await fetch('https://api.actumx.app/v1/protected/quote?topic=general', {
  headers: {
    'x-api-key': 'actumx_live_abc123...',
    'x-payment-id': settlement.paymentId,
    'x-payment-proof': settlement.receiptId
  }
});
const data = await response3.json();

Query Parameters

string

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

Request Headers (For Retry)

string

required

Your API key

string

Payment ID from the 402 response

string

Receipt ID from the settlement response

Response (402 Payment Required)

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

string

Error code: “payment_required”

string

Human-readable message

object

x402 protocol details

Show x402 object

string

Protocol version (“0.1-draft”)

string

Unique payment identifier

number

Cost in cents (25 cents = $0.25)

number

Cost in USD

string

Currency code (“USD”)

string

The endpoint being accessed

string

Where to settle the payment

string

Payment facilitator identifier

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:

object

Response data

Show data object

string

Requested topic

string

Information about x402

string

ISO 8601 timestamp

object

Payment details

Show payment object

string

Transaction ID

string

Receipt ID

number

Amount paid

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"
  }'

const response = await fetch('https://api.actumx.app/v1/x402/settle', {
  method: 'POST',
  headers: {
    'x-api-key': 'actumx_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentId: 'x402tx_xyz789'
  })
});
const data = await response.json();

Request Body

string

required

Payment ID from the 402 response

Minimum length: 6 characters
Format: x402tx_[random_string]

Response

string

Unique receipt identifier (use as payment proof)

string

The payment ID that was settled

string

Payment status (“settled”)

number

Amount deducted in cents

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

​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