API Reference

XyncPay REST API

Complete reference for the XyncPay protocol translation API. Register agents, create spending sessions, translate payments across x402, MPP, and AP2, and confirm on-chain settlement, all through a single REST interface.

Base URLhttps://api.xyncpay.com

Guides →

Base URL

API Base URL

All API requests are made against the following base URL. All endpoints accept and return JSON. Responses follow a consistent envelope format with a top-level data field for successful responses and an error field for failures.

https://api.xyncpay.com

Security

Authentication

All endpoints require two headers for wallet-based authentication. XyncPay never stores private keys. The signature proves wallet ownership without exposing secrets.

Header	Description
X-Wallet-Address	Your agent's wallet address (e.g. `0x1a2B...9cDE`)
X-Wallet-Signature	EIP-191 signature of the JSON-stringified request body

Generate the signature by signing the exact JSON string of the request body with your wallet's private key:

const signature = await wallet.signMessage(
  JSON.stringify(requestBody)
);

For GET requests with no body, sign an empty object: {}

Limits

Rate Limits

Rate limits are enforced per wallet address and per IP. Exceeding the limit returns a 429 status with a Retry-After header indicating when the window resets.

Scope	Limit	Window
General API calls	100 requests	per minute per wallet
Agent registrations	10 requests	per hour per IP

Agents

Register and query agent wallets. Each agent is identified by a unique xyncId and linked to a single wallet address across one or more chains.

POST/v1/agents/register

Request Body

{
  "xyncId": "agent-weather-bot-01",
  "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
  "preferredChain": "base",
  "supportedProtocols": ["x402", "mpp"],
  "supportedChains": ["base"]
}

Field	Type	Required	Description
xyncId	string	Yes	Unique agent identifier (3-64 chars, alphanumeric and hyphens)
walletAddress	string	Yes	EVM wallet address (must match X-Wallet-Address header)
preferredChain	string	Yes	Default chain for settlement (e.g. "base")
supportedProtocols	string[]	Yes	Protocols the agent can handle: "x402", "mpp", "ap2"
supportedChains	string[]	Yes	Chains the agent can transact on

Response

201

{
  "data": {
    "xyncId": "agent-weather-bot-01",
    "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
    "preferredChain": "base",
    "supportedProtocols": ["x402", "mpp"],
    "supportedChains": ["base"],
    "reputationScore": 0,
    "totalTransactions": 0,
    "createdAt": "2026-04-06T12:00:00.000Z"
  }
}

Error

400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "xyncId must be between 3 and 64 characters",
    "status": 400
  }
}

GET/v1/agents/:xyncId

Retrieve details for a registered agent, including reputation score, transaction count, and supported protocols.

Path Parameters

Parameter	Type	Description
xyncId	string	The unique agent identifier assigned during registration

Response

200

{
  "data": {
    "xyncId": "agent-weather-bot-01",
    "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
    "preferredChain": "base",
    "supportedProtocols": ["x402", "mpp"],
    "supportedChains": ["base"],
    "reputationScore": 87,
    "totalTransactions": 1243,
    "totalVolume": "52340000000",
    "registeredAt": "2026-01-15T08:30:00.000Z",
    "lastActiveAt": "2026-04-06T11:42:00.000Z"
  }
}

Error

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent with xyncId 'agent-unknown' not found",
    "status": 404
  }
}

Sessions

Sessions enforce spending caps and rate limits for agent payment flows. They are required for MPP-protocol transactions and optional for x402 and AP2. Each session tracks cumulative spend and expires after the configured duration.

POST/v1/sessions/create

Create a new spending session with a defined cap, per-transaction limit, and expiration. Returns a session ID used in subsequent payment requests.

Request Body

{
  "agentId": "agent-weather-bot-01",
  "spendingCap": "50000000",
  "perTransactionLimit": "5000000",
  "allowedProtocols": ["x402", "mpp"],
  "allowedChains": ["base"],
  "expiresInSeconds": 3600
}

Field	Type	Required	Description
agentId	string	Yes	The xyncId of the registered agent
spendingCap	string	Yes	Maximum total spend in base units (e.g. "50000000" = 50 USDC)
perTransactionLimit	string	Yes	Maximum amount per individual transaction in base units
allowedProtocols	string[]	Yes	Protocols permitted within this session
allowedChains	string[]	Yes	Chains permitted within this session
expiresInSeconds	number	Yes	Session duration in seconds (max 86400 = 24 hours)

Response

201

{
  "data": {
    "sessionId": "sess-7f3a9b2c-e1d4-4a8f-b6c5-3d2e1f0a9b8c",
    "agentId": "agent-weather-bot-01",
    "spendingCap": "50000000",
    "perTransactionLimit": "5000000",
    "totalSpent": "0",
    "transactionCount": 0,
    "allowedProtocols": ["x402", "mpp"],
    "allowedChains": ["base"],
    "status": "active",
    "createdAt": "2026-04-06T12:00:00.000Z",
    "expiresAt": "2026-04-06T13:00:00.000Z"
  }
}

Error

400

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "expiresInSeconds must not exceed 86400",
    "status": 400
  }
}

GET/v1/sessions/:sessionId

Retrieve the current state of a spending session, including cumulative spend, transaction count, and remaining capacity.

Path Parameters

Parameter	Type	Description
sessionId	string	UUID returned from the create session endpoint

Response

200

{
  "data": {
    "sessionId": "sess-7f3a9b2c-e1d4-4a8f-b6c5-3d2e1f0a9b8c",
    "agentId": "agent-weather-bot-01",
    "spendingCap": "50000000",
    "perTransactionLimit": "5000000",
    "totalSpent": "12500000",
    "remainingCap": "37500000",
    "transactionCount": 4,
    "allowedProtocols": ["x402", "mpp"],
    "allowedChains": ["base"],
    "status": "active",
    "createdAt": "2026-04-06T12:00:00.000Z",
    "expiresAt": "2026-04-06T13:00:00.000Z"
  }
}

Error

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Session 'sess-invalid' not found",
    "status": 404
  }
}

Payments

The core of XyncPay. Translate payment instructions between protocols, retrieve payment status, and confirm on-chain settlement. XyncPay returns unsigned transactions. Your agent signs and submits directly. Funds never pass through XyncPay.

Core Endpoint

This is the primary endpoint for protocol translation. It accepts a payment request in one protocol format and returns an unsigned transaction for the target protocol's settlement chain.

POST/v1/payments/translate

Translate a payment request from one protocol to another. Returns an unsigned transaction that the agent signs and submits to the blockchain for settlement.

Required Headers

Header	Description
X-Wallet-Address	Wallet address of the paying agent
X-Wallet-Signature	EIP-191 signature of the JSON request body

Request Body

{
  "sourceProtocol": "x402",
  "targetProtocol": "mpp",
  "payeeAddress": "0xServiceProvider1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "amount": "1000000",
  "currency": "USDC",
  "chain": "base",
  "sessionId": "sess-7f3a9b2c-e1d4-4a8f-b6c5-3d2e1f0a9b8c"
}

Field	Type	Required	Description
sourceProtocol	string	Yes	Inbound protocol: "x402", "mpp", or "ap2"
targetProtocol	string	Yes	Outbound protocol: "x402", "mpp", or "ap2"
payeeAddress	string	Yes	Wallet address of the payment recipient
amount	string	Yes	Payment amount in base units (e.g. "1000000" = 1 USDC)
currency	string	Yes	Token symbol (currently "USDC")
chain	string	Yes	Settlement chain (e.g. "base")
sessionId	string	No	Session ID for spending cap enforcement (required for MPP)

Response

201

{
  "data": {
    "paymentId": "pay-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "sourceProtocol": "x402",
    "targetProtocol": "mpp",
    "payerAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
    "payeeAddress": "0xServiceProvider1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "amount": "1000000",
    "currency": "USDC",
    "chain": "base",
    "feeAmount": "10000",
    "netAmount": "990000",
    "feeRecipient": "0xa402496f983000c648494400dcb16B9E57ed2142",
    "status": "pending_signature",
    "unsignedTransaction": {
      "chainId": 8453,
      "to": "0x1bd714Fbb90A6a7DbdE630d313bF7959e3e125Cb",
      "data": "0xb3d76188000000000000000000000000...",
      "value": "0",
      "gasLimit": "150000"
    },
    "createdAt": "2026-04-06T12:05:00.000Z",
    "expiresAt": "2026-04-06T12:10:00.000Z"
  }
}

Error:Chain Mismatch

400

{
  "error": {
    "code": "CHAIN_MISMATCH",
    "message": "Source and target protocols must settle on the same chain",
    "status": 400
  }
}

Error:Spending Cap

400

{
  "error": {
    "code": "SPENDING_CAP_EXCEEDED",
    "message": "Amount 6000000 exceeds session per-transaction limit of 5000000",
    "status": 400
  }
}

Error:Unauthorized

401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Wallet signature does not match the provided address",
    "status": 401
  }
}

GET/v1/payments/:requestId

Retrieve the current status and details of a payment request. Use this to poll for settlement confirmation after submitting the signed transaction.

Path Parameters

Parameter	Type	Description
requestId	string	The payment ID returned from the translate endpoint

Response

200

{
  "data": {
    "id": "pay-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "sourceProtocol": "x402",
    "targetProtocol": "mpp",
    "payerAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
    "payeeAddress": "0xServiceProvider1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "amount": "1000000",
    "currency": "USDC",
    "chain": "base",
    "feeAmount": "10000",
    "netAmount": "990000",
    "status": "confirmed",
    "txHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
    "blockNumber": 28451023,
    "gasUsed": "127432",
    "createdAt": "2026-04-06T12:05:00.000Z",
    "confirmedAt": "2026-04-06T12:05:14.000Z"
  }
}

Payment Status Values

pending_signaturesubmittedconfirmedfailedexpired

POST/v1/payments/:requestId/confirm

Confirm on-chain settlement by providing the transaction hash. XyncPay verifies the transaction against the expected parameters and updates the payment status.

Path Parameters

Parameter	Type	Description
requestId	string	The payment ID to confirm

Request Body

{
  "txHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b"
}

Field	Type	Required	Description
txHash	string	Yes	On-chain transaction hash from the signed and submitted transaction

Response

200

{
  "data": {
    "id": "pay-a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
    "status": "confirmed",
    "txHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
    "blockNumber": 28451023,
    "gasUsed": "127432",
    "feeAmount": "10000",
    "netAmount": "990000",
    "confirmedAt": "2026-04-06T12:05:14.000Z"
  }
}

Error:Session Expired

400

{
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Session sess-7f3a9b2c expired at 2026-04-06T13:00:00.000Z",
    "status": 400
  }
}

Reference

Error Codes

All error responses follow a consistent envelope format. The error.code field is a stable, machine-readable identifier you can match against in your agent logic.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description of the error",
    "status": 400
  }
}

Code	Status	Description
VALIDATION_ERROR	400	Request body failed schema validation. Check required fields and value formats.
UNAUTHORIZED	401	Missing or invalid wallet signature. Ensure X-Wallet-Address and X-Wallet-Signature headers are present and the signature matches the request body.
NOT_FOUND	404	The requested resource (agent, session, or payment) does not exist.
RATE_LIMITED	429	Too many requests. Back off and retry after the duration specified in the Retry-After header.
CHAIN_MISMATCH	400	The source and target protocols must settle on the same chain for a single translation request.
SPENDING_CAP_EXCEEDED	400	The requested amount exceeds the session spending cap or per-transaction limit.
SESSION_EXPIRED	400	The session has passed its expiration time and can no longer be used for payments.
INTERNAL_ERROR	500	An unexpected error occurred on the server. Contact support if the issue persists.