Machine-payable protocol API

Create and manage ECDSA wallets for agents to make autonomous payments using the x402 machine-payable protocol. Agents can hold USDC balances and make HTTP requests that include automatic payment negotiation.

All MPP endpoints require session authentication. Wallet private keys are stored server-side and cannot be retrieved after creation.

List wallets

GET /api/agent/mpp?action=list-wallets

Returns all registered agent wallets.

Response

{
  "wallets": [
    {
      "agentId": "agent_123",
      "companyId": "company_456",
      "address": "0xabc...123"
    }
  ]
}

Field	Type	Description
`wallets`	array	List of registered agent wallets
`wallets[].agentId`	string	Agent identifier
`wallets[].companyId`	string	Company identifier
`wallets[].address`	string	Wallet address (hex format)

Get wallet

GET /api/agent/mpp?action=get-wallet&agentId=agent_123

Returns the wallet address for a specific agent.

Query parameters

Parameter	Type	Required	Description
`action`	string	Yes	Must be `get-wallet`
`agentId`	string	Yes	Agent identifier

Response

{
  "agentId": "agent_123",
  "address": "0xabc...123"
}

Errors

Code	Description
404	Wallet not found for the specified agent

Get balance

GET /api/agent/mpp?action=get-balance&agentId=agent_123

Returns the USDC balance for an agent’s wallet.

Query parameters

Parameter	Type	Required	Description
`action`	string	Yes	Must be `get-balance`
`agentId`	string	Yes	Agent identifier

Response

{
  "agentId": "agent_123",
  "balance": "10.50"
}

Errors

Code	Description
500	Failed to fetch balance (for example, RPC error)

List endpoints

GET /api/agent/mpp

When no action parameter is provided, returns the list of available endpoints.

{
  "endpoints": {
    "GET /api/agent/mpp?action=list-wallets": "List all agent wallets",
    "GET /api/agent/mpp?action=get-wallet&agentId=xxx": "Get wallet for specific agent",
    "GET /api/agent/mpp?action=get-balance&agentId=xxx": "Get USDC balance",
    "POST /api/agent/mpp": "Create or manage wallet"
  }
}

Create wallet

POST /api/agent/mpp

Creates a new ECDSA wallet for an agent. The private key is stored server-side and cannot be retrieved.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `create-wallet`
`agentId`	string	Yes	Agent identifier
`companyId`	string	Yes	Company identifier

{
  "action": "create-wallet",
  "agentId": "agent_123",
  "companyId": "company_456"
}

Response

{
  "success": true,
  "agentId": "agent_123",
  "companyId": "company_456",
  "address": "0xabc...123",
  "message": "Wallet created. Private key stored server-side — it cannot be recovered!"
}

Errors

Code	Description
400	`agentId and companyId required`

Register wallet

POST /api/agent/mpp

Registers an existing wallet for an agent by providing its private key.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `register-wallet`
`agentId`	string	Yes	Agent identifier
`companyId`	string	Yes	Company identifier
`privateKey`	string	Yes	Wallet private key (hex format)

Response

{
  "success": true,
  "agentId": "agent_123",
  "companyId": "company_456",
  "address": "0xabc...123"
}

Errors

Code	Description
400	`agentId, companyId, and privateKey required`

Make payment

POST /api/agent/mpp

Makes an HTTP request on behalf of an agent with automatic x402 payment negotiation. When the target URL returns a 402 Payment Required response, the agent’s wallet is used to authorize the payment.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `make-payment`
`agentId`	string	Yes	Agent identifier (must have a registered wallet)
`url`	string	Yes	Target URL to request
`method`	string	No	HTTP method (default: `GET`)
`headers`	object	No	Additional request headers
`body`	object	No	Request body (JSON-serialized automatically)

{
  "action": "make-payment",
  "agentId": "agent_123",
  "url": "https://api.example.com/paid-resource",
  "method": "GET"
}

Response

{
  "success": true,
  "result": {}
}

Field	Type	Description
`result`	any	The response from the target URL after payment negotiation

Errors

Code	Description
400	`url required`
400	`Invalid action`
402	Payment failed (for example, insufficient balance or payment negotiation error)
500	Internal error

Common errors

Code	Description
401	Unauthorized — session authentication required
500	Internal error

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

Machine-payable protocol API

Machine-payable protocol API

List wallets

Response

Get wallet

Query parameters

Response

Errors

Get balance

Query parameters

Response

Errors

List endpoints

Create wallet

Request body

Response

Errors

Register wallet

Request body

Response

Errors

Make payment

Request body

Response

Errors

Common errors

​Machine-payable protocol API

​List wallets

​Response

​Get wallet

​Query parameters

​Response

​Errors

​Get balance

​Query parameters

​Response

​Errors

​List endpoints

​Create wallet

​Request body

​Response

​Errors

​Register wallet

​Request body

​Response

​Errors

​Make payment

​Request body

​Response

​Errors

​Common errors

Machine-payable protocol API

List wallets

Response

Get wallet

Query parameters

Response

Errors

Get balance

Query parameters

Response

Errors

List endpoints

Create wallet

Request body

Response

Errors

Register wallet

Request body

Response

Errors

Make payment

Request body

Response

Errors

Common errors