Get a bridge quote

Get a bridge quote

post

Quote moving USDC into or out of a Hyperliquid account.

This is how you fund an account before trading and take funds off it afterwards — the perp endpoints move value only inside Hyperliquid, never across chains. Quoting places no transaction and moves no funds.

Supported routes: deposits into Hyperliquid from Ethereum, Base, Arbitrum, Polygon and BNB Chain; withdrawals from Hyperliquid to Ethereum, Base and Arbitrum. Any other pair is rejected with a 422.

Choose the balance. On the Hyperliquid leg, pass perps or spot as the token to say which balance the funds land in (deposit) or come from (withdrawal). perps is usable as margin immediately; spot is not, and needs /api/v1/perp/transfer afterwards. Sourcing a withdrawal from the wrong balance is the usual reason one fails as insufficient on a wallet that looks funded.

Amounts are in the origin token's base units, and the two sides of a Hyperliquid route are not on the same scale — USDC has 8 decimals on Hyperliquid and 6 on the EVM chains. A wrong scale is quoted without any error, so before signing check the decoded amount_in and amount_out in the response, including each one's token name: it is the only field that distinguishes the perps balance from the spot balance.

What to do next depends on execution_type:

• evm_transaction (a deposit) — the steps carry transactions you sign and broadcast yourself on the origin chain. They do not go through this API.

• hyperliquid_signature (a withdrawal) — sign the step's typed data and submit it to /api/v1/perp/bridge/execute.

Either way, follow it to completion with /api/v1/perp/bridge/status, using the request_id returned here.

Authorizations

ApiKeyAuth

apikeystringRequired

API key for authentication

Body

application/json

Transfer to quote: moving USDC into or out of a Hyperliquid account.

wallet_addressstringRequired

User's wallet address on the source chain

Example: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

origin_chainstring · enumRequired

Source chain

Example: basePossible values:

destination_chainstring · enumRequired

Destination chain

Example: hyperliquidPossible values:

origin_tokenstringRequired

Token address on the source chain. For a Hyperliquid source (withdrawal) this selects which balance is debited: pass "perps" for the perpetuals balance or "spot" for the spot balance (or the balance's token id directly). Sourcing from the wrong balance is why a withdrawal can fail with an insufficient-balance error while the total balance looks sufficient.

Example: 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913

destination_tokenstringRequired

Token address on the destination chain. For a Hyperliquid destination (deposit) this selects which balance the funds land in: pass "perps" for the perpetuals balance (immediately tradeable) or "spot" for the spot balance (not usable as perp margin until transferred). You may pass the balance's token id directly instead of the alias. The all-zero EVM address is not a valid Hyperliquid destination.

Example: perps

amountstringRequired

Amount to bridge, in the origin chain's base units (integer string, no decimal point). The scale is the ORIGIN token's own decimals, and the two sides of a Hyperliquid route do NOT match: Hyperliquid USDC has 8 decimals (1 USDC = "100000000"), EVM USDC on Base/Arbitrum/Ethereum has 6 decimals (1 USDC = "1000000"). A wrong scale is accepted without error and silently quotes the wrong size (e.g. an 8-decimal amount on a 6-decimal origin is 100x too large; the reverse is 100x too small). Always confirm the decoded amount_in in the response before signing.

Example: 1000000

slippage_bpsinteger · max: 10000Optional

Slippage tolerance in basis points (default 50 = 0.5%)

Default: 50

recipientany ofOptional

Destination wallet address (defaults to wallet_address)

stringOptional

Responses

200

Bridge quote with execution steps, decoded amounts and fee breakdown

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1/perp/bridge/quote

HTTPcURLJavaScriptPython

POST /api/v1/perp/bridge/quote HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 263

{
  "wallet_address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "origin_chain": "base",
  "destination_chain": "hyperliquid",
  "origin_token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "destination_token": "perps",
  "amount": "1000000",
  "slippage_bps": 50,
  "recipient": "text"
}

{
  "steps": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "fees": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "details": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "amount_in": {
    "amount": "text",
    "amount_formatted": "text",
    "decimals": 1,
    "symbol": "text",
    "name": "text",
    "amount_usd": "text"
  },
  "amount_out": {
    "amount": "text",
    "amount_formatted": "text",
    "decimals": 1,
    "symbol": "text",
    "name": "text",
    "amount_usd": "text"
  },
  "execution_type": "evm_transaction",
  "request_id": "text",
  "ANY_ADDITIONAL_PROPERTY": "anything"
}