XyncPay Developer Docs

npm install ethers

# .env.local
XYNCPAY_API_URL=https://www.xyncpay.com
WALLET_ADDRESS=0xYourWalletAddress
PRIVATE_KEY=0xYourPrivateKey

import { Wallet } from "ethers";

const API = process.env.XYNCPAY_API_URL;
const wallet = new Wallet(process.env.PRIVATE_KEY);

// Step 1: request a challenge
const r1 = await fetch(`${API}/api/v1/agents/register`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    walletAddress: wallet.address,
    preferredChain: "base",
  }),
});
const { data: { challenge, nonce } } = await r1.json();

// Step 2: sign the challenge and complete registration
const signature = await wallet.signMessage(challenge);
const r2 = await fetch(`${API}/api/v1/agents/register`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    walletAddress: wallet.address,
    preferredChain: "base",
    signature,
    nonce,
    name: "my-agent",
    supportedProtocols: ["x402", "mpp"],
    supportedChains: ["base"],
  }),
});

const { data: agent } = await r2.json();
console.log("xyncId:", agent.xyncId); // e.g. xync_6b8dd882f7a94bcb

const sessionBody = JSON.stringify({
  agentId: agent.xyncId,
  spendingCap: "10000000",        // 10 USDC (6 decimals)
  perTransactionLimit: "5000000", // 5 USDC per transaction
  allowedChains: ["base"],
  allowedCurrencies: ["USDC"],
  expiresInSeconds: 3600,
});

const sessionRes = await fetch(`${API}/api/v1/sessions/create`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Wallet-Address": wallet.address,
    "X-Wallet-Signature": await wallet.signMessage(sessionBody),
  },
  body: sessionBody,
});

const { data: session } = await sessionRes.json();
console.log("Session:", session.sessionId); // e.g. sess_488b8111cdaa4539a5be

const body = JSON.stringify({
  sourceProtocol: "x402",
  targetProtocol: "mpp",
  payeeAddress: "0xRecipientAddress",
  amount: "1000000",
  currency: "USDC",
  chain: "base",
  sessionId: session.sessionId,
});

const response = await fetch(`${API}/api/v1/payments/translate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Wallet-Address": wallet.address,
    "X-Wallet-Signature": await wallet.signMessage(body),
  },
  body,
});

const { data: payment } = await response.json();
console.log("Fee:", payment.request.feeAmount, payment.request.currency);
console.log("Payment ID:", payment.paymentId);

import { Wallet, JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider("https://mainnet.base.org");
const signer = new Wallet(process.env.PRIVATE_KEY, provider);

const signedTx = await signer.signTransaction(payment.unsignedTransaction);
const txResponse = await provider.broadcastTransaction(signedTx);
const receipt = await txResponse.wait();

console.log("Settled:", receipt.hash);

console.log(`View on BaseScan: https://basescan.org/tx/${receipt.hash}`);

import { ethers } from "ethers";

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);

const body = JSON.stringify({
  sourceProtocol: "x402",
  targetProtocol: "mpp",
  payeeAddress: "0xRecipientAddress",
  amount: "1000000",
  currency: "USDC",
  chain: "base",
});

const signature = await wallet.signMessage(body);

const response = await fetch(`${process.env.XYNCPAY_API_URL}/api/v1/payments/translate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Wallet-Address": wallet.address,
    "X-Wallet-Signature": signature,
  },
  body,
});

fee = max(amount * 0.01, 0.001)
fee = min(fee, 1.00)

// Equivalent:
// fee = clamp(amount * 1% / 100 scaled, $0.001, $1.00)

// FeeSplit contract (simplified)
// Both transfers execute atomically in the translated transaction

struct Split {
  address recipient;     // merchant / service provider
  uint256 amount;        // payment amount minus fee
  address feeCollector;  // XyncPay fee address
  uint256 feeAmount;     // calculated fee
}

// The unsignedTransaction returned by /api/v1/payments/translate
// already encodes the FeeSplit call. No extra work needed.

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

const response = await fetch(`${API}/v1/payments/translate`, {
  method: "POST",
  headers: { /* ... */ },
  body: translateBody,
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case "SESSION_EXPIRED":
    case "SESSION_EXHAUSTED":
      // create a new session and retry
      break;
    case "RATE_LIMIT_EXCEEDED":
      const retryAfter = response.headers.get("Retry-After");
      await new Promise((r) => setTimeout(r, Number(retryAfter) * 1000));
      // retry the request
      break;
    default:
      throw new Error(`XyncPay error [${error.code}]: ${error.message}`);
  }
}