Skip to content

End-to-end swap

This guide runs a complete self-funded swap on the Vector API: find the token pair, fetch ranked quotes, inspect the winning route, build executable calldata, submit it from your own wallet, and track the result.

Prerequisites

  • An Edith API key, sent as an api-key header on every request — Get API access.
  • A funded wallet you can sign and broadcast transactions from.
  • Amounts are base-10 integer strings in the token's base units: 1 WETH is "1000000000000000000".

1. Find the token pair

GET /search-token matches tokens by symbol, name, or exact address.

curl "https://vector.example.com/search-token?query=USDC&chainId=84532" \
  -H "api-key: $EDITH_API_KEY"

Each hit carries address, chainId, decimals, name, symbol, and an optional logoUrl. See Search tokens.

2. Fetch ranked quotes

GET /quote returns an array of route candidates, best first.

curl "https://vector.example.com/quote?fromChain=84532&toChain=84532\
&fromToken=0x4200000000000000000000000000000000000006\
&toToken=0x036CbD53842c5426634e7929541eC2318f3dCF7e\
&amount=1000000000000000000&sender=0xYourWalletAddress\
&slippage=0.5&routeMode=max_value" \
  -H "api-key: $EDITH_API_KEY"

const params = new URLSearchParams({
  fromChain: "84532",
  toChain: "84532",
  fromToken: "0x4200000000000000000000000000000000000006",
  toToken: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
  amount: "1000000000000000000",
  sender: "0xYourWalletAddress",
  slippage: "0.5",
  routeMode: "max_value",
});
const res = await fetch(`https://vector.example.com/quote?${params}`, {
  headers: { "api-key": process.env.EDITH_API_KEY! },
});
const { code, data: routes } = await res.json();
const best = routes[0];

The parameters that matter here:

Parameter Notes
fromChain, toChain Numeric chain ids. Equal for a same-chain swap; cross-chain pairs currently return an empty route list.
fromToken, toToken Token contract addresses.
amount Input amount, base-10 integer string. Anything else is rejected with a 400.
sender The address that will sign and submit the built transaction.
receiver Optional; defaults to sender.
slippage Optional percentage (0.5 = 0.5%). Default 0.5. Sets minAmountOut.
routeMode Optional ranking: max_value (default, highest output), fastest (lowest estimated time), suggested (balances both).

The full parameter list, including feeBps for integrator fees, is in Get quote routes.

3. Inspect the route

Each element of data is a route (abridged):

{
  "code": 0,
  "data": [
    {
      "quoteId": "9f8c1d2e…",
      "amount": "1000000000000000000",
      "amountOut": "3421000000",
      "minAmountOut": "3403895000",
      "expiry": 1753791245,
      "slippage": 0.5,
      "routeKind": "sameChainSwap",
      "path": [
        {
          "type": "swap",
          "provider": { "name": "Uniswap V3", "type": "dex" },
          "fromToken": "0x4200000000000000000000000000000000000006",
          "toToken": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
          "amount": "1000000000000000000",
          "amountOut": "3421000000"
        }
      ],
      "sender": "0xYourWalletAddress",
      "receiver": "0xYourWalletAddress"
    }
  ],
  "message": "success"
}

Check three things before building: minAmountOut is the slippage-protected floor you will receive at worst, expiry is a Unix timestamp (seconds) after which the quote can no longer be built, and path lists each execution leg with its provider. Keep the quoteId — it drives the next call.

4. Build the calldata

POST /build-path-by-id turns a stored quote into an executable transaction.

curl -X POST "https://vector.example.com/build-path-by-id" \
  -H "api-key: $EDITH_API_KEY" \
  -H "content-type: application/json" \
  -d '{"quoteId": "9f8c1d2e…", "simulation": false}'

const res = await fetch("https://vector.example.com/build-path-by-id", {
  method: "POST",
  headers: {
    "api-key": process.env.EDITH_API_KEY!,
    "content-type": "application/json",
  },
  body: JSON.stringify({ quoteId: best.quoteId }),
});
const { data: tx } = await res.json();

{
  "code": 0,
  "data": {
    "allowanceTarget": "0x5b73C5498c1E3b4dbA84de0F1833c4a029d90519",
    "chain": 84532,
    "data": "0x8119c065…",
    "expiry": 1753791245,
    "gasLimit": "250000",
    "simulation": false,
    "to": "0x5b73C5498c1E3b4dbA84de0F1833c4a029d90519",
    "value": "0"
  },
  "message": "success"
}

5. Approve and submit

  1. If the input token is an ERC-20, approve allowanceTarget to spend at least amount of fromToken.
  2. From the sender address, sign and broadcast a transaction with the returned to, data, value, and gasLimit.

6. Track the swap

GET /status resolves the swap from the source transaction hash:

curl "https://vector.example.com/status?txHash=0xYourTxHash&fromChain=84532" \
  -H "api-key: $EDITH_API_KEY"

data.status is one of pending, src_confirmed, completed, or failed; hashes not yet indexed report pending. Poll until it reaches completed or failed. Full response shape: Get transaction status.

Handle expired quotes

Quotes are only buildable until expiry. After that, /build-path-by-id returns a 404:

{ "code": 404, "data": null, "message": "quote expired" }

An unknown or evicted quoteId returns "quote not found or expired". Either way, do not retry the build — request a fresh quote and build the new quoteId.

Info

If you don't need to show the user a route before executing, Build best path collapses steps 2–4 into one call — see Same-chain token swap.

Next