/swap - Velora Docs

Get a Market route and ready-to-broadcast tx in one call

curl --request GET \
  --url https://api.velora.xyz/swap

{
  "priceRoute": {
    "blockNumber": 123,
    "network": 1,
    "srcToken": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "srcDecimals": 123,
    "srcAmount": "1000000000000000000",
    "destToken": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "destDecimals": 123,
    "destAmount": "1000000000000000000",
    "bestRoute": [
      {}
    ],
    "gasCostUSD": "<string>",
    "gasCost": "<string>",
    "version": "<string>",
    "contractAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "tokenTransferProxy": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "contractMethod": "<string>",
    "partnerFee": 123,
    "srcUSD": "<string>",
    "destUSD": "<string>",
    "partner": "<string>",
    "maxImpactReached": true,
    "hmac": "<string>"
  },
  "txParams": {
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "value": "0",
    "data": "<string>",
    "gasPrice": "16000000000",
    "maxFeePerGas": "<string>",
    "maxPriorityFeePerGas": "<string>",
    "gas": "<string>",
    "chainId": 1
  }
}

GET

swap

Get a Market route and ready-to-broadcast tx in one call

curl --request GET \
  --url https://api.velora.xyz/swap

{
  "priceRoute": {
    "blockNumber": 123,
    "network": 1,
    "srcToken": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "srcDecimals": 123,
    "srcAmount": "1000000000000000000",
    "destToken": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "destDecimals": 123,
    "destAmount": "1000000000000000000",
    "bestRoute": [
      {}
    ],
    "gasCostUSD": "<string>",
    "gasCost": "<string>",
    "version": "<string>",
    "contractAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "tokenTransferProxy": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "contractMethod": "<string>",
    "partnerFee": 123,
    "srcUSD": "<string>",
    "destUSD": "<string>",
    "partner": "<string>",
    "maxImpactReached": true,
    "hmac": "<string>"
  },
  "txParams": {
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "value": "0",
    "data": "<string>",
    "gasPrice": "16000000000",
    "maxFeePerGas": "<string>",
    "maxPriorityFeePerGas": "<string>",
    "gas": "<string>",
    "chainId": 1
  }
}

GET /swap fuses the two Market steps into one request: it runs aggregator pricing and calldata generation server-side and hands back both the priceRoute and ready-to-broadcast txParams. One round-trip takes you from “what’s the rate?” to a transaction you can sign and send.

Prefer the two-step flow (GET /prices → POST /transactions/:chainId) when you need to inspect or cache the route before committing, manage allowances yourself, or attach permit / permit2 data. /swap trades that control for a single call.

When to use it

Reach for `/swap` when…	Use the two-step flow when…
You want the fastest path from quote to signable tx	You need to inspect, display, or cache the `priceRoute` first
One server round-trip matters (latency, simplicity)	You attach `permit` / `permit2` to skip the approve tx
Server-built calldata with defaults is fine	You need RFQ liquidity or finer routing/fee control

Response

A 200 returns two objects:

priceRoute — the routing plan: bestRoute, srcAmount / destAmount, gasCost / gasCostUSD, srcUSD / destUSD, contractMethod, version, and an hmac integrity tag. Same shape as GET /prices.
txParams — a broadcastable tx envelope: from, to (the Augustus v6.2 router), value, data (encoded swap), gasPrice, and chainId. No gas field — estimate it locally.

{
  "priceRoute": {
    "blockNumber": 20184108,
    "network": 1,
    "srcToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "srcDecimals": 6,
    "srcAmount": "1000000",
    "destToken": "0x6b175474e89094c44da98b954eedeac495271d0f",
    "destDecimals": 18,
    "destAmount": "997620341641628401",
    "bestRoute": ["…"],
    "gasCostUSD": "5.932529",
    "contractMethod": "swapExactAmountIn",
    "version": "6.2",
    "hmac": "…"
  },
  "txParams": {
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0x6a000f20005980200259b80c5102003040001068",
    "value": "0",
    "data": "0xe3ead59e…",
    "gasPrice": "16000000000",
    "chainId": 1
  }
}

Broadcasting the transaction

txParams is ready to send, but /swap skips allowance and balance checks and returns no gas field. Before broadcasting:

Approve (ERC-20 source only)

Approve the Augustus v6.2 router (txParams.to) to spend srcToken with a standard approve(to, amount). Native sources (ETH, etc.) skip this; the amount rides along in txParams.value. To drop the extra transaction, switch to the two-step flow and pass Permit / Permit2 data in the build call.

Estimate gas

Run eth_estimateGas on txParams (or simulate the call). The response omits gas by design; never broadcast with a hardcoded limit.

Sign & send

Sign txParams with the user’s wallet and broadcast. Settlement is atomic: the swap completes or reverts, and it reverts if the delivered amount falls below the slippage-adjusted minimum.

Limitations

/swap runs at lower rate limits than the individual endpoints (Pro API accounts lift them) and excludes RFQ liquidity (AugustusRFQ). For best price across every venue, or to inspect the route before building, use GET /prices.

The endpoint validates neither allowance nor balance; your client must ensure the user has approved and funded the swap.
The response carries no gas field. Always estimate locally before broadcasting.
Swap & Transfer and fees don’t apply to the swapOnUniswap* / swapOnZeroXv* contract methods. When you set a receiver or a partner fee, constrain routing with includeContractMethods=simpleSwap,multiSwap,megaSwap.
For tax tokens, DEXs and methods that can’t handle transfer-fee tokens are filtered out; declare the fee via srcTokenTransferFee / destTokenTransferFee.

Key parameters

userAddress (required) — the caller, used as the tx from and for fee/surplus accounting. When using an intermediary contract, userAddress should correspond to msg.sender and receiver to the recipient.
slippage — basis points: 100 = 1%, 250 = 2.5%, max 10000.
version — always pass 6.2 (Augustus v6.2); when omitted the API falls back to the legacy v5 router.
partner / partnerFeeBps / partnerAddress — monetize the swap; isSurplusToUser and isDirectFeeTransfer control surplus and fee routing. See Monetization.

GET /prices

Pricing only: inspect or cache the route before building.

POST /transactions/:chainId

Build calldata from a priceRoute you already hold.

How Market works

Price → build → approve → settle, end to end.

Troubleshooting

Market failure modes: symptom, cause, fix.

Query Parameters

srcToken

string

required

Source token address. A token symbol listed in /tokens can be used instead. Example uses ETH. EVM address (20 bytes, hex-encoded with 0x prefix). Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH.

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

srcDecimals

integer

Source token decimals. Can be omitted if a token symbol is used in srcToken.

destToken

string

required

Destination token address. A token symbol listed in /tokens can be used instead. Example uses USDC. EVM address (20 bytes, hex-encoded with 0x prefix). Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH.

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

destDecimals

integer

Destination token decimals. Can be omitted if a token symbol is used in destToken.

amount

string

required

srcToken amount (SELL) or destToken amount (BUY), in WEI/raw units. Token amount in WEI / raw units (no decimal point). Serialized as a string to preserve precision for amounts that exceed JavaScript Number range.

Example:

"1000000000000000000"

side

enum<string>

default:SELL

Available options:

SELL,

BUY

network

integer

EVM chain ID. Default: 1 (Mainnet). Market uses network; Delta uses chainId. EVM chain ID. Supported values today include 1 (Mainnet), 10 (Optimism), 56 (BSC), 137 (Polygon), 8453 (Base), 42161 (Arbitrum), 43114 (Avalanche), 100 (Gnosis). The set is open — call GET /chains for the live list.

Example:

1

slippage

integer

Allowed slippage in basis points (0–10000). 100 = 1%.

Required range: 0 <= x <= 10000

userAddress

string

required

Caller wallet address. Used as the transaction from. When using an intermediary contract, userAddress should correspond to msg.sender and receiver to the recipient. EVM address (20 bytes, hex-encoded with 0x prefix). Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH.

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

receiver

string

Output recipient for Swap & Transfer. Omit when swapping from/to the same account. EVM address (20 bytes, hex-encoded with 0x prefix). Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH.

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

partner

string

default:anon

Partner string. Defaults to anon which charges 1bps fee for all swaps.

partnerAddress

string

Partner fee / surplus recipient address. EVM address (20 bytes, hex-encoded with 0x prefix). Use the mixed-case placeholder 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for native ETH.

Pattern: ^0x[a-fA-F0-9]{40}$

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

partnerFeeBps

string

Partner fee in basis points.

otherExchangePrices

boolean

default:false

If true, the response includes competitor price quotes in an others object.

includeDEXS

string

Comma-separated list of DEXs to include.

excludeDEXS

string

Comma-separated list of DEXs to exclude.

includeContractMethods

string

Comma-separated list of contract methods to include.

excludeContractMethods

string

Comma-separated list of contract methods to exclude.

maxImpact

number

Bypass API price-impact check (default = 15%). Value in %.

route

string

Dash-separated list of tokens for the price route. Max 4 tokens.

srcTokenTransferFee

string

Tax in basis points charged on srcToken transfers.

destTokenTransferFee

string

Tax in basis points charged on destToken transfers.

srcTokenDexTransferFee

string

DEX-specific tax in basis points charged on srcToken transfers.

destTokenDexTransferFee

string

DEX-specific tax in basis points charged on destToken transfers.

version

enum<string>

default:5

Protocol version. Always pass 6.2 (Augustus v6.2, what these docs cover); when omitted the API falls back to the legacy v5 router.

Available options:

5,

6.2

ignoreBadUsdPrice

boolean

default:false

Skip the USD-price availability check.

takeSurplus

boolean

default:false

Collect positive slippage as surplus. Works with partnerAddress.

isCapSurplus

boolean

default:true

Cap collected surplus at 1%.

isSurplusToUser

boolean

default:false

Route positive slippage / surplus to the user instead of the partner.

isDirectFeeTransfer

boolean

default:false

Transfer the partner fee directly rather than accruing it in the Fee Vault.

Response

Optimal route plus ready-to-broadcast tx params. Calldata targets Augustus v6.2 when version=6.2.

GET /swap envelope — pricing (priceRoute) plus a ready-to-broadcast tx (txParams) in one call.

priceRoute

object

Market route block. Calldata-ready against Augustus v6.2 when version=6.2.

Show child attributes

txParams

object

Augustus calldata + tx envelope ready to broadcast.

Show child attributes

Last modified on June 10, 2026

/transactions/:chainId Overview

​When to use it

​Response

​Broadcasting the transaction

​Limitations

​Key parameters

​Related pages

GET /prices

POST /transactions/:chainId

How Market works

Troubleshooting

Query Parameters

Response

When to use it

Response

Broadcasting the transaction

Limitations

Key parameters

Related pages