XyncPay Developer Docs

npm install @xyncpay/sdk ethers

# .env.local
XYNCPAY_API_URL=https://api.xyncpay.com
WALLET_ADDRESS=0xYourWalletAddress

const response = await fetch(`${process.env.XYNCPAY_API_URL}/v1/payments/translate`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Wallet-Address": process.env.WALLET_ADDRESS,
  },
  body: JSON.stringify({
    source_protocol: "x402",
    target_protocol: "mpp",
    amount: "10.00",
    currency: "USDC",
    recipient: "0xRecipientAddress",
    chain_id: 8453,
    metadata: {
      agent_id: "agent-001",
      purpose: "api-access",
    },
  }),
});

const { unsigned_tx, fee, session_id } = await response.json();
console.log("Fee:", fee.amount, fee.currency);
console.log("Transaction ready for signing");

import { ethers } from "ethers";

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

const signedTx = await wallet.signTransaction(unsigned_tx);
const txResponse = await provider.broadcastTransaction(signedTx);
const receipt = await txResponse.wait();

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

import { ethers } from "ethers";

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

const body = JSON.stringify({
  amount: "10.00",
  currency: "USDC",
  recipient: "0xRecipientAddress",
  source_protocol: "x402",
  target_protocol: "mpp",
});

const signature = await wallet.signMessage(body);

const response = await fetch(`${process.env.XYNCPAY_API_URL}/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 unsigned_tx returned by /v1/payments/translate
// already encodes the FeeSplit call. No extra work needed.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet 0xAbc...def has 4.20 USDC but 25.00 USDC is required.",
    "details": {
      "wallet": "0xAbcdef1234567890abcdef1234567890abcdef12",
      "available": "4.20",
      "required": "25.00",
      "currency": "USDC"
    }
  }
}

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 "INSUFFICIENT_BALANCE":
      console.error(`Need ${error.details.required} ${error.details.currency}, have ${error.details.available}`);
      break;
    case "SESSION_EXPIRED":
      // create a new session and retry
      break;
    case "RATE_LIMITED":
      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}`);
  }
}