xSwap API Documentation

The first x402-enabled decentralized exchange

Welcome to the xSwap API documentation. xSwap is a revolutionary DEX where every interaction—swaps, quote lookups, limit orders, or on-chain API calls—runs through x402 micropayments. No huge gas fees, no bot spam, just tiny verified payments for each service action.

Quick Start

1. Get Your API Credentials

Unlike traditional APIs, xSwap doesn't require API keys. Instead, you'll need a Web3 wallet that supports x402 micropayments. Currently supported wallets:

• MetaMask with x402 extension
• Phantom (Solana)
• Rainbow Wallet

2. Make Your First Request

All API endpoints are available at: https://api.xswap.fun/v1

// Step 1: Initial request (will return 402)
const response = await fetch('https://api.xswap.fun/v1/quote', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    tokenA: 'SOL',
    tokenB: 'USDC',
    amount: 1.5
  })
});

// Response: 402 Payment Required
// {
//   "amount": "0.002 USDC",
//   "purpose": "Route Lookup",
//   "payment_address": "0x..."
// }

// Step 2: Repeat request with payment header
const quotResponse = await fetch('https://api.xswap.fun/v1/quote', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-Payment': 'tx:0xABCD...', // Your payment transaction hash
    'X-Payment-Amount': '0.002',
    'X-Payment-Currency': 'USDC'
  },
  body: JSON.stringify({
    tokenA: 'SOL',
    tokenB: 'USDC',
    amount: 1.5
  })
});

// Response: 200 OK
// {
//   "route": [...],
//   "estimatedOutput": 45.23,
//   "priceImpact": 0.12,
//   "fees": 0.05
// }

Authentication with x402

xSwap uses x402 micropayments instead of traditional API keys. Here's how it works:

1. Make an API request without payment headers
2. Receive a 402 Payment Required response with payment details
3. Execute the micropayment using your Web3 wallet
4. Retry the request with payment proof in headers
5. Receive your data with a 200 OK response

Payment Headers

Get Quote x402

Request a swap quote for trading between two tokens.

Request Parameters

x402 Cost

💰 0.002 USDC per quote request

Response

{
  "route": [
    {
      "protocol": "xSwap",
      "pool": "SOL/USDC",
      "fee": 0.3
    }
  ],
  "estimatedOutput": 45.23,
  "priceImpact": 0.12,
  "minimumOutput": 44.91,
  "fees": {
    "protocol": 0.05,
    "x402": 0.002
  },
  "expiresAt": 1699999999
}

Execute Swap x402

Execute a swap based on a previously fetched quote.

x402 Cost

💰 0.005 USDC per swap execution

x402 Protocol Overview

The x402 protocol is the backbone of xSwap's micropayment system. Every API interaction is metered and charged in real-time, creating a sustainable revenue model for the DEX and its liquidity providers.

Benefits of x402

• Spam Prevention: Pay-per-query instantly filters out bot spam
• Fair Pricing: Only pay for what you use, no monthly subscriptions
• LP Revenue: Liquidity providers earn from every route query
• Instant Settlement: Payments processed in the same HTTP cycle
• No API Keys: Web3-native authentication via wallet signatures

Pricing Structure

Bot Integration Guide

xSwap is designed for autonomous trading bots and AI agents. Here's a minimal example of a trading bot that uses x402:

class XSwapBot {
  constructor(walletPrivateKey) {
    this.wallet = new Web3Wallet(walletPrivateKey);
    this.baseUrl = 'https://api.xswap.fun/v1';
  }

  async getQuote(tokenA, tokenB, amount) {
    // First request - will return 402
    let response = await fetch(`${this.baseUrl}/quote`, {
      method: 'POST',
      body: JSON.stringify({ tokenA, tokenB, amount })
    });

    if (response.status === 402) {
      const paymentInfo = await response.json();
      
      // Make x402 micropayment
      const txHash = await this.wallet.pay(
        paymentInfo.payment_address,
        paymentInfo.amount
      );

      // Retry with payment proof
      response = await fetch(`${this.baseUrl}/quote`, {
        method: 'POST',
        headers: {
          'X-Payment': txHash,
          'X-Payment-Amount': paymentInfo.amount,
          'X-Payment-Currency': 'USDC'
        },
        body: JSON.stringify({ tokenA, tokenB, amount })
      });
    }

    return response.json();
  }

  async executeSwap(quote) {
    // Similar x402 flow for swap execution
    // ...
  }
}

// Usage
const bot = new XSwapBot(process.env.PRIVATE_KEY);
const quote = await bot.getQuote('SOL', 'USDC', 10);
if (quote.priceImpact < 0.5) {
  await bot.executeSwap(quote);
}

Rate Limits

Unlike traditional APIs with request-per-minute limits, xSwap uses economic rate limiting through x402 payments. There are no hard rate limits—you can make as many requests as you're willing to pay for.

© 2025 xSwap Protocol. Built with x402 micropayments. GitHub • Discord • Twitter