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://www.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://www.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

Register a new agent wallet with XyncPay using a two-step challenge-response flow. No authentication headers are required on either step.

Step 1 returns a short-lived challenge string. Step 2 submits your EIP-191 signature of that string; the server verifies wallet ownership and returns your xyncId.

Step 1: Request Challenge

POST /api/v1/agents/register
Content-Type: application/json

{
  "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
  "preferredChain": "base"
}

Field	Type	Required	Description
walletAddress	string	Yes	EVM wallet address to register
preferredChain	string	Yes	Default chain for settlement (e.g. "base")

Response

200

{
  "data": {
    "challenge": "XyncPay Registration\nWallet: 0x1a2B...\nNonce: a3f9c1b2",
    "nonce": "a3f9c1b2",
    "expiresAt": 1746403200000
  }
}

Step 2: Complete Registration

POST /api/v1/agents/register
Content-Type: application/json

{
  "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
  "preferredChain": "base",
  "signature": "0xabc123...",
  "nonce": "a3f9c1b2",
  "name": "trading-agent-alpha",
  "supportedProtocols": ["x402", "mpp"],
  "supportedChains": ["base"]
}

Field	Type	Required	Description
walletAddress	string	Yes	Same wallet address as Step 1
preferredChain	string	Yes	Default chain for settlement (e.g. "base")
signature	string	Yes	EIP-191 signature of the challenge string from Step 1
nonce	string	Yes	Nonce returned in Step 1
name	string	No	Human-readable label for the agent
supportedProtocols	string[]	No	Protocols the agent can handle: "x402", "mpp"
supportedChains	string[]	No	Chains the agent can transact on

Response

201

{
  "data": {
    "xyncId": "xync_6b8dd882f7a94bcb",
    "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
    "preferredChain": "base",
    "name": "trading-agent-alpha",
    "supportedProtocols": ["x402", "mpp"],
    "supportedChains": ["base"],
    "reputationScore": 50,
    "totalTransactions": 0,
    "totalVolumeUsd": 0,
    "status": "active",
    "createdAt": 1746403200000,
    "lastActiveAt": 1746403200000
  }
}

Errors

422Validation error (missing or malformed fields)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "walletAddress: Invalid"
  }
}

409Wallet already registered

{
  "error": {
    "code": "AGENT_EXISTS",
    "message": "An agent with this wallet address already exists"
  }
}

401Signature verification failed

{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Signature verification failed"
  }
}

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": "xync_6b8dd882f7a94bcb",
    "walletAddress": "0x1a2B3c4D5e6F7a8B9c0D1e2F3a4B5c6D7e8F9a0b",
    "preferredChain": "base",
    "supportedProtocols": ["x402", "mpp"],
    "supportedChains": ["base"],
    "reputationScore": 87,
    "totalTransactions": 1243,
    "totalVolumeUsd": 52340,
    "status": "active",
    "createdAt": 1768435200000,
    "lastActiveAt": 1775433600000
  }
}

Error

404

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

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, optional per-transaction limit, and expiration. Returns a session ID used in subsequent payment requests. Requires wallet signature.

Request Body

{
  "agentId": "xync_6b8dd882f7a94bcb",
  "spendingCap": "50000000",
  "perTransactionLimit": "5000000",
  "rateLimit": 30,
  "allowedProtocols": ["x402", "mpp"],
  "allowedChains": ["base"],
  "allowedCurrencies": ["USDC"],
  "expiresInSeconds": 3600
}

Field	Type	Required	Description
agentId	string	Yes	xyncId of the agent (xync_ followed by 16 hex chars)
spendingCap	string	Yes	Maximum total spend in base units (e.g. "50000000" = 50 USDC)
perTransactionLimit	string	No	Maximum amount per individual transaction in base units
rateLimit	number	No	Maximum transactions per minute within this session
allowedProtocols	string[]	No	Restrict session to specific protocols: "x402", "mpp"
allowedChains	string[]	No	Restrict session to specific chains
allowedCurrencies	string[]	No	Restrict session to specific currencies: "USDC", "USDT"
allowedPayees	string[]	No	Restrict session to specific payee wallet addresses
expiresInSeconds	number	Yes	Session duration in seconds (max 2592000 = 30 days)

Response

201

{
  "data": {
    "sessionId": "sess_7540666a441a4b7fbe4f",
    "agentId": "012a638f-8c4c-412f-898f-f25f47f056e0",
    "spendingCap": "50000000",
    "perTransactionLimit": "5000000",
    "totalSpent": "0",
    "transactionCount": 0,
    "rateLimit": 30,
    "allowedProtocols": ["x402", "mpp"],
    "allowedChains": ["base"],
    "allowedCurrencies": ["USDC"],
    "status": "active",
    "createdAt": 1746403200000,
    "expiresAt": 1746406800000
  }
}

Note: agentId in the response is the internal agent UUID, not the xyncId supplied in the request. createdAt and expiresAt are unix millisecond timestamps.

Error

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Max session duration: 30 days"
  }
}

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	sess_ format ID returned from the create session endpoint (e.g. sess_7540666a441a4b7fbe4f)

Response

200

{
  "data": {
    "sessionId": "sess_7540666a441a4b7fbe4f",
    "agentId": "012a638f-8c4c-412f-898f-f25f47f056e0",
    "spendingCap": "50000000",
    "perTransactionLimit": "5000000",
    "totalSpent": "12500000",
    "remainingCap": "37500000",
    "transactionCount": 4,
    "rateLimit": 30,
    "allowedProtocols": ["x402", "mpp"],
    "allowedChains": ["base"],
    "allowedCurrencies": ["USDC"],
    "status": "active",
    "createdAt": 1746403200000,
    "expiresAt": 1746406800000
  }
}

Error

404

{
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session 'sess-invalid' not found"
  }
}

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

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": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "settlementId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "unsignedTransaction": {
      "chainId": 8453,
      "to": "0x1bd714Fbb90A6a7DbdE630d313bF7959e3e125Cb",
      "data": "0xb3d76188000000000000000000000000...",
      "value": "0",
      "gasLimit": "150000",
      "maxFeePerGas": "1000000000",
      "maxPriorityFeePerGas": "100000000"
    },
    "request": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "sourceProtocol": "x402",
      "targetProtocol": "mpp",
      "amount": "1000000",
      "feeAmount": "10000",
      "netAmount": "990000",
      "currency": "USDC",
      "chain": "base"
    }
  }
}

Error:Chain Mismatch

400

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

Error:Spending Cap

400

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

Error:Unauthorized

401

{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Wallet signature verification failed"
  }
}

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": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "sourceProtocol": "x402",
    "targetProtocol": "mpp",
    "payerXyncId": "xync_6b8dd882f7a94bcb",
    "payeeAddress": "0xServiceProvider1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "amount": "1000000",
    "feeAmount": "10000",
    "netAmount": "990000",
    "currency": "USDC",
    "sourceChain": "base",
    "targetChain": "base",
    "status": "completed",
    "createdAt": 1746381900000,
    "confirmedAt": 1746381914000,
    "settlement": {
      "id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "chain": "base",
      "txHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
      "status": "confirmed",
      "blockNumber": 28451023,
      "gasUsed": "127432",
      "confirmedAt": 1746381914000
    }
  }
}

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": {
    "paymentId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "settlementId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "status": "confirmed",
    "txHash": "0x7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b",
    "blockNumber": 28451023,
    "gasUsed": "127432"
  }
}

Error:Session Expired

400

{
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Session sess_7540666a441a4b7fbe4f expired at 1746406800000"
  }
}

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

Code	Status	Description
VALIDATION_ERROR	422	Request body failed schema validation. Check required fields and value formats.
INVALID_SIGNATURE	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.