Hydrex Router API — Agent Reference

This document is a concise reference for LLM agents and AI coding assistants integrating with the Hydrex Router API.

Base URL

• ▪Swagger UI: https://router.api.hydrex.fi/api
• ▪OpenAPI spec (JSON): https://router.api.hydrex.fi/api-json
• ▪Primary chain: Base mainnet (chainId: 8453)
• ▪Auth: No API key required for public endpoints

Core Concepts

• ▪Amounts — always pass amounts as strings in base units (wei). Never floats.
  • ▪1 USDC (6 decimals) = "1000000"
  • ▪1 WETH (18 decimals) = "1000000000000000000"
• ▪Slippage — expressed in basis points (BIPS). 50 = 0.5%, 100 = 1%.
• ▪Router contract address — always read transaction.to from the quote response. Never hardcode it.
• ▪Aggregator sources: ZEROX, OPENOCEAN, OKX, KYBERSWAP

Endpoints

GET /quote ★ (primary)

Returns the best route across all aggregators plus Hydrex router calldata ready for on-chain submission.

Required parameters:

Optional parameters:

Example response:

{
  "amountIn": "100000000",
  "amountOut": "34820000000000000",
  "minOutputAmount": "34645900000000000",
  "recipient": "0xYourWallet",
  "transaction": {
    "to": "0x599bfa1039c9e22603f15642b711d56be62071f4",
    "data": "0x...",
    "value": "0"
  }
}

Key fields:

• ▪transaction.to — the Hydrex router contract address (use this, never hardcode)
• ▪transaction.data — calldata to send as-is
• ▪transaction.value — must be passed as value for native ETH swaps; always parse as BigInt
• ▪minOutputAmount — on-chain floor; transaction reverts if output is below this
• ▪amountOut — expected output amount in base units
• ▪recipient — the taker address echoed back

GET /aggregator/quote

Raw quote from a single upstream aggregator, without Hydrex router calldata. Useful for price display.

Required parameters: fromTokenAddress, toTokenAddress, amount (same as /quote).

Key differences from /quote:

• ▪chainId is optional (defaults to Base 8453)
• ▪taker is optional (but required when using OKX as source)
• ▪referral, referralFeeBps, origin, and gasPrice are not supported
• ▪Response does not include transaction calldata

GET /aggregator/quote/all

Fetches quotes from all enabled aggregators in parallel. Returns an array with one entry per source.

POST /quote/multi

Batches multiple independent swap legs into a single executeSwaps transaction. The legs do not chain (output of one is not input of the next).

Required body fields:

Optional body fields:

Each swap item:

Example request body:

{
  "taker": "0xYourWalletAddress",
  "chainId": "8453",
  "slippage": "50",
  "swaps": [
    {
      "fromTokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "toTokenAddress": "0x4200000000000000000000000000000000000006",
      "amount": "100000000"
    }
  ]
}

GET /dca/orders

Returns all DCA orders from the Hydrex DCA smart contract.

GET /dca/orders/user/{address}

Returns all DCA orders for a specific wallet address.

Executing a Swap (viem)

import { createPublicClient, createWalletClient, http, maxUint256 } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const BASE_URL = "https://router.api.hydrex.fi";
const FROM_TOKEN = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"; // USDC

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const publicClient = createPublicClient({ chain: base, transport: http() });
const walletClient = createWalletClient({ account, chain: base, transport: http() });

// 1. Get quote
const params = new URLSearchParams({
  fromTokenAddress: FROM_TOKEN,
  toTokenAddress:   "0x4200000000000000000000000000000000000006", // WETH
  amount:           "100000000", // 100 USDC
  chainId:          "8453",
  taker:            account.address,
  slippage:         "50",
});
const quote = await fetch(`${BASE_URL}/quote?${params}`).then(r => r.json());

// 2. Approve if needed (ERC-20 only)
const ERC20_ABI = [
  { name: "allowance", type: "function", stateMutability: "view",
    inputs: [{ name: "owner", type: "address" }, { name: "spender", type: "address" }],
    outputs: [{ type: "uint256" }] },
  { name: "approve", type: "function", stateMutability: "nonpayable",
    inputs: [{ name: "spender", type: "address" }, { name: "amount", type: "uint256" }],
    outputs: [{ type: "bool" }] },
];
const allowance = await publicClient.readContract({
  address: FROM_TOKEN, abi: ERC20_ABI,
  functionName: "allowance", args: [account.address, quote.transaction.to],
});
if (allowance < BigInt(quote.amountIn)) {
  const { request } = await publicClient.simulateContract({
    address: FROM_TOKEN, abi: ERC20_ABI,
    functionName: "approve", args: [quote.transaction.to, maxUint256], account,
  });
  await walletClient.writeContract(request);
}

// 3. Send transaction
const hash = await walletClient.sendTransaction({
  to:    quote.transaction.to,
  data:  quote.transaction.data,
  value: BigInt(quote.transaction.value ?? "0"),
});
const receipt = await publicClient.waitForTransactionReceipt({ hash });

Fee Integration

Referral fee (on-chain)

Deducted from the output token by the router contract. Sent to referral wallet.

amountOut and minOutputAmount in the response already reflect the fee deduction.

Spread fee (aggregator-level)

Charged at the upstream aggregator before the quote is returned.

Both can be combined in a single quote request.

Error Handling

Error responses follow the shape:

{ "statusCode": 400, "message": "MISSING_PARAMS", "details": "..." }

Common Token Addresses (Base)

Key Contracts (Base Mainnet)

Note: The Router contract address may change with protocol upgrades. Always read transaction.to from the API response rather than hardcoding it.

DCA Smart Contract

Contract name: HydrexDCA (upgradeable proxy) Proxy address (Base mainnet): 0x612697A124aB01b3AcF44c6e0135539416BF3fAB Implementation: 0x4dD152531eD13C7BB89Cd30B25246662e8DD87E4 (verified on Basescan)

The contract is custodial — it holds the full totalAmount upfront and executes each swap at the configured interval. Swaps are triggered by Hydrex operators. A 0.5% protocol fee is deducted from each output amount.

OrderCreateParams struct

struct OrderCreateParams {
    address tokenIn;          // use 0xEeee...EeEE for native ETH
    address tokenOut;
    uint256 totalAmount;      // transferred from caller at creation
    uint256 numberOfSwaps;    // min 2, max 100
    uint256 interval;         // seconds between swaps; min 60, max 365 days
    uint256 minUsdPrice;      // 0 = no floor
    uint256 maxUsdPrice;      // 0 = no ceiling
    uint256 slippageTolerance; // basis points, max 10000
}

Key functions

Key events