JavaScript Integration

The recommended way to interact with 4SEC API. The @x402/fetch SDK handles all payment logic automatically.

Installation

npm install @x402/fetch viem

Basic Usage

import { wrapFetchWithPayments } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";

// Setup wallet on Base
const account = privateKeyToAccount("0x_YOUR_PRIVATE_KEY");
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http("https://mainnet.base.org"),
});

// Create payment-enabled fetch
const fetchWithPayment = wrapFetchWithPayments(fetch, {
  client: walletClient,
});

// Make request (auto-payment!)
const res = await fetchWithPayment("https://api.foursec.xyz/price/ETH");
const data = await res.json();
console.log("ETH: $" + data.price_usd);

Multiple Symbols

const symbols = ["ETH", "BTC", "SOL", "AVAX"];

const prices = await Promise.all(
  symbols.map((s) =>
    fetchWithPayment("https://api.foursec.xyz/price/" + s)
      .then((r) => r.json())
  )
);

prices.forEach((p) => console.log(p.symbol + ": $" + p.price_usd));

DEX Endpoints

// Real-time price ($0.01)
const price = await fetchWithPayment(
  "https://api.foursec.xyz/price/ETH"
);
const priceData = await price.json();
console.log(`ETH: $${priceData.price_usd}`);

// Historical OHLCV ($0.02)
const history = await fetchWithPayment(
  "https://api.foursec.xyz/price/history/ETH?interval=1h&limit=24"
);
const historyData = await history.json();
console.log(`Candles: ${historyData.candles.length}`);

// 24h volume ($0.02)
const volume = await fetchWithPayment(
  "https://api.foursec.xyz/volume/ETH"
);
const volData = await volume.json();
console.log(`Volume: $${volData.volume_usd}`);

// Spread analysis ($0.02)
const spread = await fetchWithPayment(
  "https://api.foursec.xyz/spread/ETH-USDC"
);
const spreadData = await spread.json();
console.log(`Spread: ${spreadData.spread_percent}%`);

// Arbitrage opportunities ($0.05)
const arb = await fetchWithPayment(
  "https://api.foursec.xyz/arbitrage-opportunity"
);
const arbData = await arb.json();
console.log(`Opportunities: ${arbData.opportunities.length}`);

// Risk metrics ($0.03)
const risk = await fetchWithPayment(
  "https://api.foursec.xyz/volatility-index/ETH"
);
const riskData = await risk.json();
console.log(`VaR (95%): ${riskData.var_95}`);

// Price alert ($0.01)
const alert = await fetchWithPayment(
  "https://api.foursec.xyz/price-alert",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      symbol: "ETH",
      condition: "below",
      target_price: 2400,
      webhook_url: "https://your-bot.com/webhook",
      duration_hours: 24
    })
  }
);
const alertData = await alert.json();
console.log(`Alert created: ${alertData.alert_id}`);

Funding Rate Endpoints

// Current funding rate ($0.03)
const funding = await fetchWithPayment(
  "https://api.foursec.xyz/funding-rate/ETH"
);
const fundingData = await funding.json();
console.log(`Funding rate: ${fundingData.funding_rate}%`);

// Historical funding rates ($0.04)
const fundingHistory = await fetchWithPayment(
  "https://api.foursec.xyz/funding-rate/history/ETH?limit=100"
);
const fundingHistoryData = await fundingHistory.json();
console.log(`Historical rates: ${fundingHistoryData.rates.length}`);

// Extreme funding rates ($0.05)
const extreme = await fetchWithPayment(
  "https://api.foursec.xyz/funding-rate/extreme"
);
const extremeData = await extreme.json();
extremeData.symbols.forEach(s => {
  console.log(`${s.symbol}: ${s.funding_rate}%`);
});

Liquidation Endpoints

// Liquidation heatmap ($0.04)
const heatmap = await fetchWithPayment(
  "https://api.foursec.xyz/liquidation/heatmap/ETH"
);
const heatmapData = await heatmap.json();
console.log(`Liquidation levels: ${heatmapData.levels.length}`);

// Recent liquidations ($0.03)
const recent = await fetchWithPayment(
  "https://api.foursec.xyz/liquidation/recent"
);
const recentData = await recent.json();
console.log(`Recent events: ${recentData.events.length}`);

// Liquidation alert ($0.06)
const liqAlert = await fetchWithPayment(
  "https://api.foursec.xyz/liquidation/alert"
);
const liqAlertData = await liqAlert.json();
console.log(`Alert status: ${liqAlertData.status}`);

CEX Market Data (v1)

// Aggregated CEX prices ($0.02)
const cexPrices = await fetchWithPayment(
  "https://api.foursec.xyz/api/v1/prices?symbols=btc,eth,sol"
);
const cexPricesData = await cexPrices.json();
cexPricesData.prices.forEach(p => {
  console.log(`${p.symbol}: $${p.current_price}`);
});

// CEX market details ($0.03)
const market = await fetchWithPayment(
  "https://api.foursec.xyz/api/v1/market/bitcoin"
);
const marketData = await market.json();
console.log(`Market: ${marketData.name}`);
console.log(`Price: $${marketData.current_price}`);
console.log(`Volume: $${marketData.total_volume}`);

// CEX market history ($0.04)
const marketHistory = await fetchWithPayment(
  "https://api.foursec.xyz/api/v1/market/bitcoin/history?days=7"
);
const marketHistoryData = await marketHistory.json();
console.log(`Historical data: ${marketHistoryData.prices.length}`);

Error Handling

try {
  const res = await fetchWithPayment("https://api.foursec.xyz/price/XYZ");
  const data = await res.json();
} catch (err) {
  if (err.status === 404) console.log("Symbol not found");
  if (err.status === 429) console.log("Rate limited, waiting...");
  if (err.status === 402) console.log("Insufficient USDC balance");
}

Retry with Backoff

async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const res = await fetchWithPayment(url);
      if (res.ok) return await res.json();
      if (res.status === 429) {
        const wait = Math.pow(2, i) * 1000;
        await new Promise((r) => setTimeout(r, wait));
        continue;
      }
      throw new Error("HTTP " + res.status);
    } catch (err) {
      if (i === maxRetries - 1) throw err;
    }
  }
  throw new Error("Max retries exceeded");
}

Express.js Webhook Handler

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook/price-alert", (req, res) => {
  const { symbol, current_price, condition } = req.body;
  console.log("ALERT: " + symbol + " hit $" + current_price);

  // Execute trading logic here

  res.status(200).send("OK");
});

app.listen(3000);

Complete Trading Bot Example

import { wrapFetchWithPayments } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";

// Setup
const account = privateKeyToAccount("0x_YOUR_KEY");
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http("https://mainnet.base.org"),
});
const fetch = wrapFetchWithPayments(globalThis.fetch, {
  client: walletClient,
});

async function analyzeMarket(symbol) {
  // Fetch all data in parallel
  const [priceRes, arbRes, riskRes, fundingRes] = await Promise.all([
    fetch(`https://api.foursec.xyz/price/${symbol}`),
    fetch("https://api.foursec.xyz/arbitrage-opportunity"),
    fetch(`https://api.foursec.xyz/volatility-index/${symbol}`),
    fetch(`https://api.foursec.xyz/funding-rate/${symbol}`)
  ]);

  const price = await priceRes.json();
  const arb = await arbRes.json();
  const risk = await riskRes.json();
  const funding = await fundingRes.json();

  console.log(`${symbol}: $${price.price_usd}`);
  console.log(`Risk: ${risk.risk_level}`);
  console.log(`Funding: ${funding.funding_rate}%`);
  console.log(`Arb opportunities: ${arb.opportunities.length}`);

  // Cost: $0.12 per analysis cycle
  return { price, arb, risk, funding };
}

// Run every 30 seconds (leveraging cache for free repeat requests)
setInterval(() => analyzeMarket("ETH"), 30000);