Deposit addresses

A deposit address lets your user swap or bridge just by sending tokens to an address: no wallet connection, no signature in your app. You create an address for a route (for example USDC on Base → USDC on Arbitrum, delivered to your user's address), show it to your user, and every deposit to it is swapped or bridged and delivered to the recipient. It fits exchanges, games, payroll, and wallets with a "deposit from any chain" button.

Deposit addresses are non-custodial. The address is created by the liquidity provider (Relay), which picks up each deposit and delivers dstToken on dstChain. LayerHop never holds the funds; it creates the address, detects the deposits, records each one as an order and sends you webhooks.

Deposit addresses work with live (lh_live_) and test (lh_test_) keys. Build and check your integration in test mode first: test addresses are fake and deposits are simulated.

How it works#

1. Create an address with an API key: the source chain and token, the destination chain and token, the recipient, and a refundTo address on the source chain.
2. Show address to your user, with the token and chain to send (token on chainId), for example as text and a QR code.
3. Your user sends srcToken on srcChain to the address from any wallet or exchange.
4. LayerHop detects the deposit and records it as an order (quoteId starting with dep_, depositAddressId set). You get order.submitted, then order.filled (or order.refunded / order.failed) when it settles.

1. Create a deposit address#

curl -X POST https://api.layerhop.com/v1/deposit-addresses \
  -H "x-api-key: $LAYERHOP_API_KEY" -H "content-type: application/json" \
  -d '{
    "srcChain": "base",
    "srcToken": "USDC",
    "dstChain": "arbitrum",
    "dstToken": "USDC",
    "recipient": "0xUserAddressOnArbitrum",
    "refundTo": "0xUserAddressOnBase",
    "label": "user-4821"
  }'

With the TypeScript SDK:

import { LayerHop } from "@layerhop/sdk";

const lh = new LayerHop({ apiKey: process.env.LAYERHOP_API_KEY });
const da = await lh.depositAddresses.create({
  srcChain: "base",
  srcToken: "USDC",
  dstChain: "arbitrum",
  dstToken: "USDC",
  recipient: "0xUserAddressOnArbitrum",
  refundTo: "0xUserAddressOnBase",
  label: "user-4821",
});
console.log(da.address);              // show this to your user: send USDC on Base here
console.log(da.estimate.dstAmount);   // what 100 USDC would deliver, in base units

The response (201) is the deposit address: id (da_…), livemode, status (active), provider (relay, or sandbox in test mode), address, chainId and token (what to send where), dstChainId, dstToken, recipient, refundTo, reusable, amount (one-time addresses only), fees (ourFeeBps, integratorFeeBps, integrator), label, metadata, depositCount, lastDepositAt and createdAt, plus an estimate: { amount, dstAmount, dstAmountMin, estimatedSeconds }. The estimate is a guide only: each deposit is priced when it arrives.

Creating addresses uses the stricter rate-limit bucket. A route the provider cannot serve returns UNSUPPORTED_CHAIN.

2. Tell your user what to send#

Show the address together with the exact token and chain, and these rules:

• Send only srcToken on srcChain. Other tokens, or the same token on another chain, sent to this address may be lost for good. Say it clearly next to the address.
• Send at least $1 worth. Smaller deposits may never be picked up (the provider ignores deposits worth $0.05 or less). Creating an address with a smaller amount returns AMOUNT_TOO_SMALL.
• One-time addresses take exactly amount, once. An underpayment is refunded to refundTo; do not reuse the address afterwards.
• Withdrawing from an exchange works, but refunds always go to refundTo, never back to the exchange. That is why refundTo must be an address your user controls.

3. Track deposits#

Every deposit LayerHop detects becomes an order with quoteId starting with dep_ and depositAddressId set to the address id. Subscribe a webhook endpoint to the order events:

{
  "id": "evt_…",
  "type": "order.filled",
  "livemode": true,
  "createdAt": "2026-10-19T10:04:12.000Z",
  "data": {
    "order": {
      "quoteId": "dep_0x5f2c…",
      "status": "filled",
      "provider": "relay",
      "srcChainId": 8453,
      "dstChainId": 42161,
      "amount": "25000000",
      "dstAmount": "24940000",
      "depositAddressId": "da_01k7x2m4c4x8q6r0v3b5n7p9d",
      "srcTxHash": "0x…",
      "dstTxHash": "0x…"
    }
  }
}

Match the event to your user with depositAddressId (and your label or metadata on the address). The order also shows up in GET /v1/dashboard/orders, and GET /v1/deposit-addresses/{id} returns the address with its 20 most recent deposits in deposits.

How fast deposits are detected. LayerHop checks an address about every 15 seconds while a deposit is in flight or it was recently active, then backs off to at most every 15 minutes when it is idle. When your user says "I sent it", call refresh to check right away:

await lh.depositAddresses.refresh(da.id); // POST /v1/deposit-addresses/{id}/refresh → 202

4. Manage addresses#

Each address belongs to the account and mode (live or test) of the key that created it; other accounts' addresses return NOT_FOUND. Disabling stops LayerHop tracking the address (status: disabled); refreshing or simulating it then returns CONFLICT. Stop showing a disabled address to your user: the provider may still process funds sent to it later, but you will not get orders or webhooks for them.

From the CLI or an AI agent#

The CLI covers every endpoint with layerhop deposit-address (API key in --api-key or LAYERHOP_API_KEY). Amounts are in human units unless you pass --base-units; add --json for the raw API response.

export LAYERHOP_API_KEY=lh_test_…
layerhop deposit-address create USDC base USDC arbitrum --recipient 0xUserAddressOnArbitrum --refund-to 0xUserAddressOnBase --label user-4821
layerhop deposit-address simulate da_… 25        # test keys only
layerhop deposit-address get da_…                # the address and its recent deposits
layerhop deposit-address list --status active    # also: refresh <id>, disable <id>

The MCP server has the same operations as tools: create_deposit_address, list_deposit_addresses, get_deposit_address, refresh_deposit_address, disable_deposit_address and simulate_deposit (test keys only). They need an API key (LAYERHOP_API_KEY locally, the x-layerhop-api-key header on the hosted server), and every response includes the rules the agent must pass on to the user: send only srcToken on srcChain, at least $1 worth, with a refundTo that is never an exchange deposit address.

Manage them in the dashboard#

The Deposit addresses page of the dashboard lists every address of the current mode (live or test), whether it was created with an API key or in the dashboard, with its route, label, deposit count and last deposit. Open one to see its QR code, its 20 most recent deposits (status, amounts and transaction links) and its details. From there you can:

• Create an address with the same fields as the API (source token, destination token, recipient, refundTo, reusable or one-time, label). Addresses created in the dashboard belong to your account and have no API key.
• Check for deposits now (the same as refresh) and disable an address.
• Simulate a deposit in test mode, with the same magic amounts as the API.

The dashboard uses the same rules as the API: live mode needs deposit addresses enabled for your account, and each address belongs to one account and mode.

Fees#

A deposit pays the same fees as any API swap: LayerHop's API channel fee (20 bps by default, see Fees & channels) plus your partner fee if you set one. Both are fixed when you create the address and shown in fees; each deposit's order records the fee actually applied (ourFeeBps, partnerFeeBps), and your partner share counts towards your earnings and payouts like any other order.

Test mode#

With an lh_test_ key, deposit addresses are served by the sandbox: provider is sandbox and address is a fake address in the source chain's format. Never send real funds to it. Record a deposit instead:

curl -X POST https://api.layerhop.com/v1/deposit-addresses/da_…/simulate \
  -H "x-api-key: $LAYERHOP_TEST_KEY" -H "content-type: application/json" \
  -d '{ "amount": "25000000" }'

const order = await lh.depositAddresses.simulate(da.id, { amount: "25000000" });
// order.quoteId starts with dep_, order.depositAddressId === da.id, status "submitted"

The deposit becomes a submitted test order that the worker settles like any test order, with webhooks to your test endpoints. The same magic amounts choose the outcome:

A one-time test address accepts a single simulated deposit of exactly its amount. simulate on a live address returns FORBIDDEN.

Errors#

See Error handling for retries and the API reference for every field.