Skip to content

mpp.mdx

Latest commit

 

History

History
251 lines (188 loc) · 5.48 KB

mpp.mdx

File metadata and controls

251 lines (188 loc) · 5.48 KB
Raw
title Machine-payable protocol API
description Manage agent wallets and make x402-style payments on behalf of agents

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