API reference

Note

This page is generated at build time from services/api/openapi.yaml (OpenAPI 3.1.0, API version 0.1.0).

LayerHop is a meta-aggregator. GET /v1/quote asks every liquidity provider that supports the route (Jupiter, Relay, deBridge, 0x, LI.FI) in parallel and ranks the answers by time-adjusted output for the user. POST /v1/orders turns a quote into a transaction the user's own wallet signs. LayerHop never holds funds.

Conventions:

• Amounts are integer strings in base units (never floats).
• Chains are given as a numeric id or a slug (base, solana). Solana uses LayerHop's internal id 7565164.
• Tokens are given as a symbol from the built-in token list (USDC) or as an address / mint.
• Every response carries an x-request-id header; error bodies repeat it as requestId.
• Errors use one shape, { "error": { code, message, requestId, docsUrl } }, with a stable code (see the ErrorCode schema).

Base URLs#

Authentication#

• x-api-key (header) — Optional. The SDK sends it when configured, but the API does not enforce keys or rate limits yet (coming soon).

Conventions#

• All paths are under /v1. Request and response bodies are JSON.
• Every response has an x-request-id header. Error bodies repeat it as requestId.
• Non-2xx responses use the Error schema; its docsUrl points at the error catalog.

Meta#

Liveness and static registries.

Health check#

Liveness probe. Lists the providers loaded in this API instance.

Responses

Example request

curl "http://localhost:8787/v1/health"

Example response (200)

{
  "ok": true,
  "providers": [
    "jupiter",
    "relay",
    "debridge",
    "zerox",
    "lifi"
  ]
}

List chains#

Every chain LayerHop can route from or to.

Responses

Example request

curl "http://localhost:8787/v1/chains"

Example response (200)

{
  "chains": [
    {
      "id": 8453,
      "slug": "base",
      "name": "Base",
      "vm": "evm",
      "nativeSymbol": "ETH",
      "nativeDecimals": 18,
      "explorerTx": "https://basescan.org/tx/"
    },
    {
      "id": 7565164,
      "slug": "solana",
      "name": "Solana",
      "vm": "svm",
      "nativeSymbol": "SOL",
      "nativeDecimals": 9,
      "explorerTx": "https://solscan.io/tx/"
    }
  ]
}

List tokens#

The built-in token list for one chain. Symbols on this list can be used in place of addresses in GET /v1/quote. Any other token can still be quoted by address / mint.

Query parameters

Responses

Example request

curl "http://localhost:8787/v1/tokens?chain=base"

Example response (200)

{
  "tokens": [
    {
      "chainId": 8453,
      "address": "0x0000000000000000000000000000000000000000",
      "symbol": "ETH",
      "decimals": 18
    },
    {
      "chainId": 8453,
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "decimals": 6
    }
  ]
}

Quotes#

Ask every provider for a price.

Get quotes#

Fans the request out to every provider that supports the route, in parallel, with a per-provider timeout (8 s by default). Successful quotes are ranked best-for-the-user first by time-adjusted output (1 bp penalty per minute of ETA beyond the first minute, capped at 50 bps), then by speed. Providers that failed are listed in errors and do not fail the request, unless every provider failed (NO_ROUTE).

Each quote has its own quoteId; pass it to POST /v1/orders before expiresAt.

Query parameters

Responses

Example request

curl "http://localhost:8787/v1/quote?srcChain=base&srcToken=USDC&amount=100000000&dstChain=solana&dstToken=SOL&sender=0x1111111111111111111111111111111111111111&recipient=9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"

Example response (200)

{
  "best": {
    "quoteId": "q_6f1c2d0e-8a51-4c1e-9d0b-2f7a9e3c4b10",
    "provider": "relay",
    "dstAmount": "612345678",
    "dstAmountMin": "609283949",
    "estimatedSeconds": 8,
    "fees": {
      "ourFeeBps": 20,
      "providerFeeUsd": 0.12,
      "gasUsd": 0.03
    },
    "expiresAt": 1760000030
  },
  "quotes": [
    {
      "quoteId": "q_6f1c2d0e-8a51-4c1e-9d0b-2f7a9e3c4b10",
      "provider": "relay",
      "dstAmount": "612345678",
      "dstAmountMin": "609283949",
      "estimatedSeconds": 8,
      "fees": {
        "ourFeeBps": 20,
        "providerFeeUsd": 0.12,
        "gasUsd": 0.03
      },
      "expiresAt": 1760000030
    },
    {
      "quoteId": "q_0b9a4f7e-1d2c-4e3b-8a6f-5c4d3e2b1a09",
      "provider": "debridge",
      "dstAmount": "611900000",
      "dstAmountMin": "611900000",
      "estimatedSeconds": 6,
      "fees": {
        "ourFeeBps": 20
      },
      "expiresAt": 1760000030
    }
  ],
  "errors": [
    {
      "provider": "lifi",
      "code": "PROVIDER_TIMEOUT",
      "message": "Timed out: li.quest"
    }
  ]
}

Orders#

Build, submit and track the transaction for a quote.

Build the transaction#

Returns the transaction for a quote, for the user's wallet to sign. EVM transactions may carry an approval (an ERC-20 approve to send first). Solana transactions are a base64 serialized VersionedTransaction; when submitViaApi is true, sign it and send it to POST /v1/orders/submit instead of an RPC node.

The quote must not be expired. Some providers ask you to submit within ~30 s of building.

Request body — BuildOrderRequest (required)

Responses

Example request

curl -X POST "http://localhost:8787/v1/orders" \
  -H "content-type: application/json" \
  -d '{"quoteId":"q_6f1c2d0e-8a51-4c1e-9d0b-2f7a9e3c4b10"}'

Example response (200)

{
  "quoteId": "q_6f1c2d0e-8a51-4c1e-9d0b-2f7a9e3c4b10",
  "provider": "relay",
  "tx": {
    "vm": "evm",
    "chainId": 8453,
    "to": "0xa5F565650890fBA1824Ee0F21EbBbF660a179934",
    "data": "0x58109c...",
    "value": "0",
    "approval": {
      "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "spender": "0xa5F565650890fBA1824Ee0F21EbBbF660a179934",
      "amount": "100000000"
    }
  }
}

Submit a signed transaction#

Only for Solana transactions built with submitViaApi: true (today: Jupiter, whose RFQ and gasless transactions are co-signed and never land through a plain RPC node). Send the wallet-signed transaction as base64; LayerHop forwards it to the provider and returns the transaction signature. For every other provider this returns INVALID_PARAMS — broadcast from the wallet instead.

Request body — SubmitOrderRequest (required)

Responses

Example request

curl -X POST "http://localhost:8787/v1/orders/submit" \
  -H "content-type: application/json" \
  -d '{"quoteId":"q_6f1c2d0e-8a51-4c1e-9d0b-2f7a9e3c4b10","signedTransaction":"AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA..."}'

Example response (200)

{
  "provider": "jupiter",
  "txHash": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW"
}

Get order status#

Asks the provider for the current state of an order. What id means depends on the provider:

• relay: Relay request id or the source deposit tx hash.
• debridge: source tx hash (EVM hash or Solana signature) or a DLN order id.
• lifi: source tx hash.
• jupiter, zerox: same-chain swaps have nothing to track off-chain; the state is always unknown. Confirm the transaction on chain instead.

Poll until state is filled, refunded or failed.

Path parameters

Responses

Example request

curl "http://localhost:8787/v1/orders/relay/0x3f1e6a2b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f"

Example response (200)

{
  "provider": "relay",
  "id": "0x3f1e6a2b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f",
  "state": "filled",
  "srcTxHash": "0x3f1e6a2b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f",
  "dstTxHash": "3nKqYdW1hS8vZ4cT2pXeR7mB9uJfL6aG5oN1wQ8kE3sD7yH2xV4tC6bM9rP1zA5uF8jL2gK7eW3qS6dN4hT9vB1"
}

Schemas#

ErrorCode#

Stable error code. Each has a page at https://docs.layerhop.com/errors/{code}.

string, one of:

• INVALID_PARAMS
• UNSUPPORTED_CHAIN
• UNSUPPORTED_TOKEN
• AMOUNT_TOO_SMALL
• AMOUNT_TOO_LARGE
• NO_ROUTE
• QUOTE_NOT_FOUND
• QUOTE_EXPIRED
• ORDER_NOT_FOUND
• PROVIDER_ERROR
• PROVIDER_TIMEOUT
• RATE_LIMITED
• UNAUTHORIZED
• INTERNAL

Error#

Every non-2xx response has this body.

ProviderId#

Liquidity provider. Loaded by default: jupiter, relay, debridge, zerox, lifi. mayan is quote-only and disabled; odos is shut down; mock exists only in local development (LAYERHOP_ENABLE_MOCK=1).

string, one of:

• jupiter
• relay
• debridge
• mayan
• zerox
• odos
• lifi
• mock

FeeChannel#

Where the trade comes from; decides LayerHop's fee. Defaults: web 30 bps, widget 30 bps, api 20 bps, bot 90 bps (operators can override them).

string, one of:

• web
• widget
• bot
• api

Vm#

Virtual machine family. svm is Solana.

string, one of:

• evm
• svm

Chain#

Token#

HealthResponse#

ChainsResponse#

TokensResponse#

FeeBreakdown#

Quote#

ProviderError#

A provider that failed while the request as a whole succeeded.

QuoteResponse#

Approval#

An ERC-20 approve(spender, amount) on token that must be mined before the main transaction.

EvmTx#

SvmTx#

BuiltTx#

The transaction for the user's wallet, discriminated by vm.

One of: EvmTx · SvmTx, discriminated by vm.

BuildOrderRequest#

BuildOrderResponse#

SubmitOrderRequest#

SubmitOrderResponse#

OrderState#

pending in flight · filled delivered · refunded returned to the sender · failed · unknown the provider cannot tell (yet), or does not track this kind of order.

string, one of:

• pending
• filled
• refunded
• failed
• unknown

OrderStatus#