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