API v1 Integration

This document describes the XSwap API integration.

XSwap Route Generation API

The XSwap Route Generation API provides optimal cross-chain and single-chain swap routes with integrated bridging capabilities. This endpoint calculates the most efficient path for token swaps across supported blockchain networks.

Endpoint: POST https://xswap.link/api/route/v1 Content-Type: application/json

Authentication

All requests require a valid integratorId that must be registered with XSwap. Contact the XSwap team to obtain your integrator credentials. Apply Here.

Request Format

HTTP Method: POST /api/route Headers: Content-Type: application/json

The request body must contain a JSON object with the following parameters:

Core Parameters

fromChain (required)

• Type: string

• Validation: Must be a supported source chain identifier

• Description: The blockchain network where the swap originates

• Example: "1" (Ethereum), "137" (Polygon), "42161" (Arbitrum)

toChain (required)

• Type: string

• Validation: Must be a supported destination chain identifier

• Description: The blockchain network where the swap concludes

• Example: "1" (Ethereum), "43114" (Avalanche)

fromToken (required)

• Type: string

• Validation: Valid Ethereum address (0x format, 40 hex characters)

• Description: Contract address of the source token on the origin chain

toToken (required)

• Type: string

• Validation: Valid EVM address

• Description: Contract address of the destination token on the target chain

fromAmount (required)

• Type: string

• Validation: Numeric string representation

• Description: Amount of source tokens to swap, specified in the token's smallest unit

• Example: "1000000000000000000" (1 token with 18 decimals)

fromAddress (required)

• Type: string

• Validation: Valid Ethereum address

• Description: Wallet address initiating the swap transaction

• Example: "0x742d35Cc6634C0532925a3b8D7389a82C95e1234"

toAddress (required)

• Type: string

• Validation: Valid EVM or Solana address

• Description: Recipient wallet address for the destination tokens

• Example: "0x742d35Cc6634C0532925a3b8D7389a82C95e1234"

paymentToken (required)

• Type: string

• Validation: Valid Ethereum address

• Description: Token used for paying cross-chain fees (typically native token)

• Example: "0x0000000000000000000000000000000000000000" (native chain currency)

integratorId (required)

• Type: string

• Validation: Must be a registered integrator identifier

• Description: Unique identifier for API access and fee attribution

• NOTE: If you do not have one, Apply Here.

slippage (required)

• Type: number

• Validation: Floating-point number

• Description: Maximum acceptable slippage percentage (e.g., 1.0 = 1%)

• Range: Typically 0.1 to 3.0

• Example: 0.5 (0.5% slippage tolerance)

expressDelivery (required)

• Type: boolean

• Description: Enable instant execution on the destination chain

• Default: false

• Note: Additional fees apply when enabled

Optional Parameters

infiniteApproval

• Type: boolean (optional)

• Description: Approve a maximum uint256 amount

• Default: true

• Security Note: Consider implications for token security

quoteOnly

• Type: boolean (optional)

• Description: Return route estimation without generating executable transactions

• Default: false

• Use Case: Price discovery and route analysis

integratorFee

• Type: number (optional)

• Validation: Integer between 1 and 1000

• Description: Additional fee charged by integrator (in basis points)

• Example: 1000 (1.00% fee)

• Requirement: Must be provided with integratorFeeReceiverAddress

integratorFeeReceiverAddress

• Type: string (optional)

• Validation: Valid Ethereum address

• Description: Address to receive integrator fees

• Requirement: Must be provided with integratorFee

Example Request

{
    "integratorId": "xxx",
    "fromChain": "1",
    "toChain": "56",
    "fromAddress": "0x5BAb475094E3Aa8ccA7f75Af41f01E95982E8294",
    "toAddress": "0x5BAb475094E3Aa8ccA7f75Af41f01E95982E8294",
    "fromToken": "0x0000000000000000000000000000000000000000",
    "toToken": "0x0000000000000000000000000000000000000000",
    "fromAmount": "1000000000000000000",
    "slippage": 1.5,
    "paymentToken": "0x0000000000000000000000000000000000000000",
    "expressDelivery": true,
    "infiniteApproval": true
}

Response Format

Success Response (200 OK)

{
  "estAmountOut": "3903691707210627856",
  "minAmountOut": "3845136331602468438",
  "transactions": {
    "swap": {
      "to": "0xe1c14b9f065dead2e89ee35382f8bd42bdb87a04",
      "data": "0x20f5e02000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000009d70576d8e253bcf00000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000090000000000000000000000000000000000000000000000000000000000000e10d80000000000000000000000005BAb475094E3Aa8ccA7f75Af41f01E95982E82940000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000362cb2ecd0ed7b1000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001e0000000000000000000000000000000000000000000000000000000000000032000000000000000000000000000000000000000000000000000000000000006e000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004aae823a6a0b376de6a78e74ecc5b079d38cbcf7000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000006423b872dd000000000000000000000000e1c14b9f065dead2e89ee35382f8bd42bdb87a040000000000000000000000007bc7942e589c85ca9ac78cd8d2e53e9de58a5ec700000000000000000000000000000000000000000000000000584b8c8d22d90a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004aae823a6a0b376de6a78e74ecc5b079d38cbcf7000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000044095ea7b3000000000000000000000000111111125421ca6dc452d289314280a0f8842a6500000000000000000000000000000000000000000000000000584b8c8d22d90a0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000111111125421ca6dc452d289314280a0f8842a65000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000003a000000000000000000000000000000000000000000000000000000000000002c807ed2379000000000000000000000000de9e4fe32b049f821c7f3e9802381aa470ffca730000000000000000000000004aae823a6a0b376de6a78e74ecc5b079d38cbcf7000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000de9e4fe32b049f821c7f3e9802381aa470ffca730000000000000000000000007bc7942e589c85ca9ac78cd8d2e53e9de58a5ec700000000000000000000000000000000000000000000000000584b8c8d22d90a000000000000000000000000000000000000000000000000355cab1f061d1e5600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000017c00000000000000000000000000000000000000000000015e0001480000fe00a007e5c0d20000000000000000000000000000000000000000000000da00009e00004f02a00000000000000000000000000000000000000000000000000056e69b95d9fbfbee63c1e501575a951ad021d4297ac125be88ee4620652d5c124aae823a6a0b376de6a78e74ecc5b079d38cbcf702a0000000000000000000000000000000000000000000000000355cab1f061d1e56ee63c1e5016bbc40579ad1bbd243895ca0acb086bb6300d6367130d2a12b9bcbfae4f2634d864a1ee1ce3ead9c4101bb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c00042e1a7d4d000000000000000000000000000000000000000000000000000000000000000000a0f2fa6b66eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000000000000000000000000000362cb2ecd0ed7b100000000000000000001aac58348c6a4ec061111111125421ca6dc452d289314280a0f8842a650000000066e0bbe3000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000005BAb475094E3Aa8ccA7f75Af41f01E95982E8294000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000007a56e1c57c7475ccf742a1832b028f0456652f97000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000014000000000000000000000000000000000000000000000000000000000000007e07a7dc0a218ef582a960cffe25aef3e7c1c311a8aaa74df33d6aeddba36504d0600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001e0000000000000000000000000000000000000000000000000000000000000032000000000000000000000000000000000000000000000000000000000000004a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000111111125421ca6dc452d289314280a0f8842a650000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000006889af926a00000000000000000000000000000000000000000000000000584b8c8d22d90a2000000000000000000000004585fe77225b41b697c938b018e2ac67ac5a20c02080000000000000000000005738df8073ad05d0c0fcf60e358033268ebf16cc66e0bbe3000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000007a56e1c57c7475ccf742a1832b028f0456652f97000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000044a9059cbb000000000000000000000000e1c14b9f065dead2e89ee35382f8bd42bdb87a0400000000000000000000000000000000000000000000000000584b8c8d22d90a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000007a56e1c57c7475ccf742a1832b028f0456652f97000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000044095ea7b3000000000000000000000000e5219a1dd02407690a192010a0f33be036b5510800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000007a56e1c57c7475ccf742a1832b028f0456652f9700000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001000000000000000000000000e5219a1dd02407690a192010a0f33be036b55108000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a0000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000000a485da82440000000000000000000000007a56e1c57c7475ccf742a1832b028f0456652f970000000000000000000000005BAb475094E3Aa8ccA7f75Af41f01E95982E82940000000000000000000000000000000000000000000000000058a6538a9e5c7c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000007a56e1c57c7475ccf742a1832b028f0456652f97000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000000",
      "value": "1002609833292468298"
    }
  },
  "xSwapFees": {
    "ccipFee": "2148108829292169",
    "xSwapFee": {
      "tokenFee": "0",
      "nativeFee": "246913580246913"
    },
    "expressDeliveryFee": "0"
  }
}

Response Fields

estAmountOut

• Type: string

• Description: Estimated output amount in the destination token's smallest unit

minAmountOut

• Type: string

• Description: Minimum guaranteed output considering slippage

transactions

• Type: Transaction[]

• Description: Array of transactions to execute for the complete swap

xSwapFees

• Type: object

• Description: Breakdown of all fees associated with the swap

Error Responses

400 Bad Request

{
  "error": "Invalid integrator id",
  "message": "The provided integrator ID is not registered"
}

429 Too Many Requests

{
  "error": "You are limited to 100 RPM",
  "message": "Rate limit exceeded for integrator"
}

500 Internal Server Error

{
  "error": "Route generation failed",
  "message": "Unable to find suitable liquidity path"
}