Soheil Router

Soheil Router

One API call for the best token swap price, and one transaction that makes it. Soheil Router compares prices across DEXes and aggregators on each network and executes the trade through its own contract: non-upgradeable, source verified on the explorers, and it holds no funds between trades.

• Docs: https://soheil.fi/developers/docs/
• Free API key: https://soheil.fi/developers/dashboard/
• OpenAPI 3.1: https://api.soheil.fi/v1/openapi.json
• For AI assistants: https://soheil.fi/developers/llms-full.txt · MCP server at https://api.soheil.fi/v1/mcp

Fees

0.1% (10 bps) to the router on each swap. You can add your own fee (up to 0.9%), paid to your wallet inside the same transaction: nothing to claim.

Install

npm install github:soheil-fi/soheil-router

Quick start

import { COIN, SoheilRouter } from "@soheil-fi/router";

const router = new SoheilRouter({ apiKey: process.env.SOHEIL_ROUTER_KEY }); // keep the key on your server

const quote = await router.getQuote({
  fromChainId: 8453,                                       // Base
  fromToken: COIN,                                         // ETH
  toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",   // USDC
  fromAmount: 10n ** 15n,                                  // 0.001 ETH, in wei
  fromAddress: "0xUserWallet",
  integratorBps: 30,                                       // your fee: 0.3%
});

// quote.approvalAddress → approve exactly quote.fromAmount first (null when selling the coin)
// quote.transactionRequest → have the user's wallet send it unchanged
const status = await router.waitForTrade(8453, txHash);     // DONE, REFUNDED, FAILED or NOT_OURS

A whole swap with viem is in examples/swap-viem.ts.

Method	Key	Returns
getNetworks()	no	Live networks, our contract and the contracts a trade may call
getInfo()	no	Fee, limits, docs
getQuote(request)	yes	Price, minimum received, fees, approval address, transaction
getStatus(chainId, txHash)	yes	PENDING, DONE, REFUNDED, FAILED, NOT_OURS or NOT_FOUND
waitForTrade(chainId, txHash)	yes	getStatus until the trade is final

Errors are thrown as SoheilRouterError with code (NO_ROUTE, RATE_LIMITED, UNAUTHORIZED…), the HTTP status and a message safe to show your users.

Bridge to another network

Set toChainId to another of the router's networks. The answer has type: "bridge", and the user still signs one transaction on the source network; the recipient is paid on the destination within seconds.

const quote = await router.getQuote({
  fromChainId: 8453,                                       // from Base
  toChainId: 42161,                                        // to Arbitrum
  fromToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
  toToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",   // USDC on Arbitrum
  fromAmount: 100_000_000n,                                // 100 USDC
  fromAddress: "0xUserWallet",
});
// quote.toAmount is what arrives; a transfer nobody fills is refunded to fromAddress on Base (status REFUND_PENDING until then)
const status = await router.waitForTrade(8453, txHash);     // DONE (status.receiving = the payout) or REFUNDED

fromToken and toToken can be any token: what the bridge does not carry is swapped first on the source network, or bought on arrival on the destination (then toAmountMin is that swap's least; if the price moves past it, the recipient gets the bridged token, like USDC, instead). Still one transaction, fees taken once. Docs: https://soheil.fi/developers/docs/bridging/

Use it from an AI assistant (MCP)

The API is also an MCP server (Streamable HTTP) with the tools get_networks, get_api_info, get_quote and get_trade_status.

claude mcp add --transport http soheil-router https://api.soheil.fi/v1/mcp \
  --header "Authorization: Bearer $SOHEIL_ROUTER_KEY"

{ "mcpServers": { "soheil-router": { "url": "https://api.soheil.fi/v1/mcp", "headers": { "Authorization": "Bearer sk_your_key" } } } }

Good to know

• Amounts are integer strings in the token's smallest unit; use bigint, never JavaScript numbers.
• Approve exactly fromAmount, never an unlimited amount.
• The user always signs in their own wallet: the API never holds keys or funds.

Built by Soheil.fi. Questions: [email protected]

License

MIT