Getting Started with Surge Swap Router API

Surge Swap router is a wrapper around the 1 click near intents API that simplifies cross-chain swapping implementation. It provides transaction payloads, token icons, and routing through multiple DeFi protocol providers to enable seamless token swaps across blockchains.

How It Works

The API returns everything you need for frontend integration: quote data, token metadata, icons, and ready-to-execute transaction payloads. The swap process:

Get a quote - Returns transaction payload and deposit address
Send tokens - User transfers tokens to the deposit address
Automatic execution - NEAR intents process the cross-chain swap
Receive tokens - Tokens delivered to specified recipient address

Base URL: https://app.surgeswap.xyz/api

Step 1: Get Dry Quote

Start by getting a dry quote to see exchange rates, fees, and estimated output amounts without committing to the swap.

Request

curl -X POST "https://app.surgeswap.xyz/api/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "dry": true,
    "fromTokenSymbol": "ETH",
    "fromChain": "eth",
    "toTokenSymbol": "USDC",
    "toChain": "arb",
    "amount": "0.01"
  }'

Parameters

dry: Set to true for quote only
amount: Token units (e.g. "0.01" for 0.01 ETH, not wei)
fromTokenSymbol / toTokenSymbol: Token symbols (see Tokens API)
fromChain / toChain: Chain identifiers

Response

{
  "success": true,
  "quote": {
    "amountIn": "10000000000000000",
    "amountInFormatted": "0.01",
    "amountInUsd": "46.3356",
    "amountOut": "46178904",
    "amountOutFormatted": "46.178904",
    "amountOutUsd": "46.1703",
    "minAmountOut": "45717061",
    "timeEstimate": 44
  },
  "fromToken": {
    "symbol": "ETH",
    "decimals": 18,
    "blockchain": "eth"
  },
  "toToken": {
    "symbol": "USDC",
    "decimals": 6,
    "blockchain": "arb"
  }
}

Step 2: Get Real Quote

Once you're happy with the dry quote, get the actual executable quote with deposit address and transaction payloads.

Request

curl -X POST "https://app.surgeswap.xyz/api/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "dry": false,
    "fromTokenSymbol": "ETH",
    "fromChain": "eth",
    "toTokenSymbol": "USDC",
    "toChain": "arb",
    "amount": "0.01",
    "refundAddress": "0x742d35Cc6C5d7CdB0B5e5d8ae54a8de8b4b7f4B3",
    "recipientAddress": "0x8ba1f109551bD432803012645Hac136c22C501e5"
  }'

Parameters

dry: Set to false for executable transactions
refundAddress: Your address (where refunds go if swap fails)
recipientAddress: Where you want output tokens sent

Response

The response includes all the quote information plus transaction payloads:

{
  "success": true,
  "quote": {
    "depositAddress": "0x76b4c56085ED136a8744D52bE956396624a730E8",
    "amountIn": "10000000000000000",
    "amountInFormatted": "0.01",
    "amountOut": "46178904",
    "amountOutFormatted": "46.178904",
    "timeEstimate": 44
  },
  "nearTxs": [...],
  "evmTx": {
    "to": "0x...",
    "data": "0x...",
    "value": "10000000000000000",
    "chainId": 1
  },
  "solTx": "...",
  "suiTx": {...}
}

Step 3: Send Transactions

Take the transaction payload from your quote response and sign it with your wallet. The format depends on the blockchain:

EVM Chains (Ethereum, Base, Arbitrum, etc.)

import { useAccount, useSendTransaction, useSwitchChain } from 'wagmi';
 
function executeEvmTransaction(quote) {
  const { sendTransactionAsync } = useSendTransaction();
  const { switchChainAsync } = useSwitchChain();
  const { chainId: currentChainId } = useAccount();
  
  const targetChainId = quote.evmTx.chainId;
  
  if (targetChainId && currentChainId !== targetChainId) {
    await switchChainAsync({ chainId: targetChainId });
  }
  
  const txHash = await sendTransactionAsync({
    to: quote.evmTx.to,
    data: quote.evmTx.data,
    value: BigInt(quote.evmTx.value),
  });
  
  return txHash;
}

NEAR Protocol

import { useBitteWallet } from '@bitte-ai/react';
 
function executeNearTransaction(quote) {
  const { selector } = useBitteWallet();
  
  const wallet = await selector.wallet();
  const result = await wallet.signAndSendTransactions({
    transactions: quote.nearTxs,
  });
  
  return result?.[0]?.transaction?.hash;
}

Solana

import { useWallet } from '@solana/wallet-adapter-react';
import { Connection, Transaction } from '@solana/web3.js';
 
function executeSolanaTransaction(quote) {
  const { sendTransaction } = useWallet();
  
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=your-key');
  const transaction = Transaction.from(Buffer.from(quote.solTx, 'base64'));
  
  const signature = await sendTransaction(transaction, connection);
  return signature;
}

Sui

import { useWallet } from '@suiet/wallet-kit';
import { Transaction } from '@mysten/sui/transactions';
 
function executeSuiTransaction(quote) {
  const { signAndExecuteTransaction } = useWallet();
  
  const transaction = Transaction.from(quote.suiTx);
  const result = await signAndExecuteTransaction({ transaction });
  
  return result.digest;
}

Step 4: Submit Transaction Hash (Optional)

Speed up swap processing by notifying the system about your deposit transaction:

Endpoint

POST https://1click.chaindefuser.com/v0/deposit/submit

Request

curl -X POST "https://1click.chaindefuser.com/v0/deposit/submit" \
  -H "Authorization: Bearer JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "txHash": "0x123abc456def789",
    "depositAddress": "0x2527D02599Ba641c19FEa793cD0F167589a0f10D"
  }'

Parameters

txHash: Transaction hash of your deposit
depositAddress: Deposit address from the quote

Response

{
  "quoteResponse": {
    "timestamp": "2019-08-24T14:15:22Z",
    "signature": "text",
    "quote": {
      "depositAddress": "0x76b4c56085ED136a8744D52bE956396624a730E8",
      "amountIn": "1000000",
      "amountOut": "9950000",
      "timeEstimate": 120
    }
  },
  "status": "KNOWN_DEPOSIT_TX",
  "updatedAt": "2025-08-29T16:01:21.802Z"
}

Step 5: Query Swap Status

Check the status of your swap using the deposit address from your quote:

Endpoint

GET https://1click.chaindefuser.com/v0/status

Request

curl -X GET "https://1click.chaindefuser.com/v0/status?depositAddress=0x76b4c56085ED136a8744D52bE956396624a730E8" \
  -H "Authorization: Bearer JWT"

Parameters

depositAddress: Deposit address from the quote
depositMemo: Required if the quote response included a deposit memo

Response

{
  "quoteResponse": {
    "quote": {
      "depositAddress": "0x76b4c56085ED136a8744D52bE956396624a730E8",
      "amountIn": "1000000",
      "amountOut": "9950000",
      "timeEstimate": 120
    }
  },
  "status": "KNOWN_DEPOSIT_TX",
  "updatedAt": "2025-08-29T16:01:21.802Z",
  "swapDetails": {
    "intentHashes": ["text"],
    "nearTxHashes": ["text"],
    "amountIn": "1000",
    "amountOut": "9950000",
    "originChainTxHashes": [
      {
        "hash": "0x123abc456def789",
        "explorerUrl": "text"
      }
    ],
    "destinationChainTxHashes": [
      {
        "hash": "0x123abc456def789",
        "explorerUrl": "text"
      }
    ]
  }
}

Supported Chains

Chain	ID	Type
Ethereum	`eth`	From/To
Base	`base`	From/To
Arbitrum	`arb`	From/To
Gnosis	`gnosis`	From/To
BNB Smart Chain	`bsc`	From/To
Polygon	`pol`	From/To
NEAR Protocol	`near`	From/To
Solana	`sol`	From/To
Sui	`sui`	From/To
Bitcoin	`btc`	To only
Zcash	`zec`	To only
Dogecoin	`doge`	To only
TRON	`tron`	To only
XRP	`xrp`	To only
Berachain	`bera`	To only

Error Handling

{
  "success": false,
  "error": "Unsupported token: INVALID on eth",
  "validationErrors": {
    "recipientInvalid": true,
    "mockAddresses": true,
    "invalidAmount": true
  }
}

Tokens API