Full Example

import crypto from "crypto";

let ethers;
async function loadEthers() {
  if (!ethers) {
    try {
      ethers = (await import("ethers")).ethers;
    } catch {
      throw new Error("ethers is required. Run: npm install ethers");
    }
  }
  return ethers;
}

async function getSignerAddress() {
  const { computeAddress } = await loadEthers();
  return computeAddress(CONFIG.PRIVATE_KEY);
}

// ─── Configuration ───────────────────────────────────────────────
const CONFIG = {
  // Ratio API base URL (Sandbox by default). The "/api/router" prefix is not part
  // of the HMAC string-to-sign — requests are signed over "/v1/..." paths.
  API_BASE: process.env.RATIO_API_BASE || "https://sbx.ratiofx.com/api/router",
  API_KEY: process.env.RATIO_API_KEY || "",
  API_SECRET: process.env.RATIO_API_SECRET || "",

  // Blockchain
  RPC_URL: process.env.RPC_URL || "https://public-en-kairos.node.kaia.io",
  PRIVATE_KEY: process.env.PRIVATE_KEY || "",

  // Swap parameters (override via env or change here)
  // PAIR is used to find the corridor; FROM_TOKEN/TO_TOKEN determine swap direction.
  PAIR: process.env.SWAP_PAIR || "USDT-JPYC",
  // Set FROM_TOKEN and TO_TOKEN to the ERC-20 contract addresses.
  // These are resolved automatically from the corridor if left empty.
  FROM_TOKEN: process.env.FROM_TOKEN || "",
  TO_TOKEN: process.env.TO_TOKEN || "",
  AMOUNT: process.env.SWAP_AMOUNT || "2000",
};

// ─── HMAC Authentication ─────────────────────────────────────────
function signRequest(method, path, body = null) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyStr = body ? JSON.stringify(body) : "";

  // POST requests require x-ratio-request-id for replay protection.
  // It is included in the HMAC payload between timestamp and method.
  const isMutating = method !== "GET";
  const requestId = isMutating ? `req-${timestamp}-${crypto.randomUUID()}` : null;

  const payload = requestId
    ? timestamp + requestId + method + path + bodyStr
    : timestamp + method + path + bodyStr;
  const signature = crypto
    .createHmac("sha256", CONFIG.API_SECRET)
    .update(payload)
    .digest("hex");

  const headers = {
    "x-ratio-api-key": CONFIG.API_KEY,
    "x-ratio-timestamp": timestamp,
    "x-ratio-signature": signature,
    "Content-Type": "application/json",
  };
  if (requestId) headers["x-ratio-request-id"] = requestId;

  return { headers, bodyStr };
}

async function ratioRequest(method, path, body = null) {
  const { headers, bodyStr } = signRequest(method, path, body);
  const url = CONFIG.API_BASE + path;
  const opts = { method, headers };
  if (method === "POST") opts.body = bodyStr;

  const res = await fetch(url, opts);
  const text = await res.text();

  let json;
  try {
    json = JSON.parse(text);
  } catch {
    throw new Error(`${method} ${path} → ${res.status} (non-JSON): ${text.slice(0, 300)}`);
  }
  if (!json.success) {
    throw new Error(`${method} ${path} → ${res.status}: ${json.error?.code} — ${json.error?.message}`);
  }
  return json;
}

async function ratioGet(path) { return ratioRequest("GET", path); }
async function ratioPost(path, body) { return ratioRequest("POST", path, body); }

// ─── Step 1: Check available corridors & resolve swap tokens ─────
async function checkCorridors() {
  console.log("\n=== Step 1: Checking available corridors ===");
  const { data } = await ratioGet("/v1/corridors");

  let target = null;
  for (const c of data.corridors) {
    console.log(`  ${c.pair}  state=${c.state ?? "N/A"}  status=${c.state_status}  directions=${JSON.stringify(c.allowed_directions)}`);
    console.log(`    limits: ${c.limits.min_amount_usd}–${c.limits.max_amount_usd} USD`);
    console.log(`    spread: base=${c.spread_config.base_spread_bps}bps  liquidity=${c.spread_config.liquidity_bps}bps`);
    if (c.pair === CONFIG.PAIR) target = c;
  }

  if (!target) throw new Error(`Corridor ${CONFIG.PAIR} not found`);

  if (!CONFIG.FROM_TOKEN || !CONFIG.TO_TOKEN) {
    CONFIG.FROM_TOKEN = target.tokens.quote.asset;
    CONFIG.TO_TOKEN = target.tokens.base.asset;
    console.log(`\n  Auto-resolved tokens for ${CONFIG.PAIR}:`);
    console.log(`    from_token (${target.tokens.quote.symbol}): ${CONFIG.FROM_TOKEN}`);
    console.log(`    to_token  (${target.tokens.base.symbol}): ${CONFIG.TO_TOKEN}`);
  }
  CONFIG.CORRIDOR_ID = target.corridor_id;
  console.log(`    corridor_id: ${CONFIG.CORRIDOR_ID}`);
  return data.corridors;
}

// ─── Step 2: Check live rates ────────────────────────────────────
async function checkRates() {
  console.log("\n=== Step 2: Checking live rates ===");
  const { data } = await ratioGet("/v1/rates");

  for (const r of data.rates) {
    console.log(`  ${r.pair}  mid=${r.mid}  age=${r.oracle_age_ms}ms  updated=${r.updated_at}`);
  }
  return data.rates;
}

// ─── Step 3: Get indicative quote ────────────────────────────────
async function getIndicativeQuote(signerAddr) {
  console.log("\n=== Step 3: Getting indicative quote ===");
  const body = {
    corridor_id: CONFIG.CORRIDOR_ID,
    from_token: CONFIG.FROM_TOKEN,
    to_token: CONFIG.TO_TOKEN,
    amount: CONFIG.AMOUNT,
    signer: signerAddr,
  };
  const { data } = await ratioPost("/v1/quote", body);

  console.log(`  ${data.amount.in.display} ${data.amount.in.token} → ${data.amount.out.display} ${data.amount.out.token}`);
  console.log(`  Fee tier: ${data.fee_breakdown.tier}`);
  console.log(`  Fixed fee: ${data.fee_breakdown.fixed.charged.display} ${data.fee_breakdown.fixed.charged.token}`);
  console.log(`  Variable fee: ${data.fee_breakdown.variable.charged.display} ${data.fee_breakdown.variable.charged.token} (${data.fee_breakdown.variable.bps}bps)`);
  console.log(`  Spread: ${data.fee_breakdown.spread.total_bps}bps`);
  console.log(`  Risk state: ${data.state_flag}  expires: ${new Date(data.expires_at * 1000).toISOString()}`);
  return data;
}

// ─── Step 4: Get firm quote ──────────────────────────────────────
async function getFirmQuote(signerAddr) {
  console.log("\n=== Step 4: Requesting firm quote ===");
  const clientRef = `TEST-${Date.now()}`;
  const body = {
    corridor_id: CONFIG.CORRIDOR_ID,
    from_token: CONFIG.FROM_TOKEN,
    to_token: CONFIG.TO_TOKEN,
    amount: CONFIG.AMOUNT,
    signer: signerAddr,
    quote_type: "FIRM",
    client_ref: clientRef,
  };
  const { data } = await ratioPost("/v1/firm-quote", body);

  console.log(`  Quote ID: ${data.quote.quote_id}`);
  console.log(`  ${data.amount.in.display} ${data.amount.in.token} → ${data.amount.out.display} ${data.amount.out.token}`);
  console.log(`  Expires: ${new Date(data.expires_at * 1000).toISOString()}`);
  console.log(`  Contract: ${data.execution.contract}`);
  console.log(`  Chain ID: ${data.execution.chain_id}`);
  console.log(`  Client ref: ${clientRef}`);
  return data;
}

// ─── Step 5: Approve token spend ─────────────────────────────────
async function ensureAllowance(firmQuote) {
  console.log("\n=== Step 5: Ensuring ERC-20 allowance ===");
  const { JsonRpcProvider, Wallet, Contract, MaxUint256 } = await loadEthers();
  const provider = new JsonRpcProvider(CONFIG.RPC_URL);
  const wallet = new Wallet(CONFIG.PRIVATE_KEY, provider);

  const fromToken = CONFIG.FROM_TOKEN;
  const spender = firmQuote.execution.contract;
  const needed = BigInt(firmQuote.execution.source_amount_raw || firmQuote.amount.in.raw);

  const erc20 = new Contract(fromToken, [
    "function allowance(address,address) view returns (uint256)",
    "function approve(address,uint256) returns (bool)",
  ], wallet);

  const current = await erc20.allowance(wallet.address, spender);
  console.log(`  Token: ${fromToken}`);
  console.log(`  Spender (FxEngine): ${spender}`);
  console.log(`  Current allowance: ${current}`);
  console.log(`  Needed: ${needed}`);

  if (current >= needed) {
    console.log("  Allowance sufficient — skipping approve.");
    return;
  }

  console.log("  Approving max allowance...");
  const tx = await erc20.approve(spender, MaxUint256);
  console.log(`  Approve tx: ${tx.hash}`);
  await tx.wait();
  console.log("  Approved.");
}

// ─── Step 6: Execute on-chain ────────────────────────────────────
async function executeOnChain(firmQuote) {
  console.log("\n=== Step 6: Executing on-chain ===");
  const { JsonRpcProvider, Wallet } = await loadEthers();
  const provider = new JsonRpcProvider(CONFIG.RPC_URL);
  const wallet = new Wallet(CONFIG.PRIVATE_KEY, provider);
  const { execution } = firmQuote;

  console.log(`  Sending tx to ${execution.contract}...`);
  const tx = await wallet.sendTransaction({
    to: execution.contract,
    data: execution.calldata,
    value: execution.value,
    chainId: execution.chain_id,
  });

  console.log(`  Submitted: ${tx.hash}`);
  console.log("  Waiting for confirmation...");
  const receipt = await tx.wait();
  console.log(`  Confirmed in block ${receipt.blockNumber} (status=${receipt.status})`);
  return tx.hash;
}

// ─── Step 7: Verify execution ────────────────────────────────────
async function verifyExecution(quoteId, txHash) {
  console.log("\n=== Step 7: Verifying execution ===");

  // Wait for indexer to catch up
  for (let attempt = 1; attempt <= 10; attempt++) {
    try {
      const { data } = await ratioGet(`/v1/executions?quote=${quoteId}`);
      console.log(`  Status: ${data.status}`);
      console.log(`  Filled rate: ${data.filled_rate}`);
      console.log(`  Source: ${data.source_amount}  Destination: ${data.destination_amount}`);
      console.log(`  Total fee (USD): ${data.total_fee_usd}`);
      console.log(`  Tx: ${data.tx_hash}`);
      console.log(`  Settled at: ${data.settled_at}`);
      return data;
    } catch (e) {
      if (attempt < 10) {
        console.log(`  Not indexed yet (attempt ${attempt}/10), waiting 3s...`);
        await new Promise((r) => setTimeout(r, 3000));
      } else {
        console.log(`  Could not verify after ${attempt} attempts. Check tx: ${txHash}`);
      }
    }
  }
}

// ─── Main ────────────────────────────────────────────────────────
async function main() {
  console.log("Ratio FX — Partner Integration Test");
  console.log(`  Pair: ${CONFIG.PAIR}  Amount: ${CONFIG.AMOUNT}`);

  // Validate config
  if (!CONFIG.API_KEY || !CONFIG.API_SECRET || !CONFIG.PRIVATE_KEY) {
    console.error("\nMissing required env vars. Set:");
    console.error("  RATIO_API_KEY, RATIO_API_SECRET, PRIVATE_KEY");
    console.error("\nOptional:");
    console.error("  RATIO_API_BASE, RPC_URL, SWAP_PAIR, FROM_TOKEN, TO_TOKEN, SWAP_AMOUNT");
    process.exit(1);
  }

  const signerAddr = await getSignerAddress();
  console.log(`  Signer wallet: ${signerAddr}`);

  await checkCorridors();
  await checkRates();
  const indicative = await getIndicativeQuote(signerAddr);

  // Execution steps (requires funded wallet)
  const firmQuote = await getFirmQuote(signerAddr);
  await ensureAllowance(firmQuote);
  const txHash = await executeOnChain(firmQuote);
  await verifyExecution(firmQuote.quote.quote_id, txHash);

  console.log("\n=== Done ===");
}

main().catch((e) => {
  console.error("\nFatal:", e.message);
  process.exit(1);
});