@layerhop/sdk

Typed TypeScript client for the LayerHop API: best-price cross-chain and same-chain swaps across EVM chains and Solana through one non-custodial API.

• Zero runtime dependencies. Uses the global fetch; works in Node 18+, browsers, Deno, Bun, edge runtimes and React Native.
• ESM + CommonJS builds with bundled type definitions.
• Never holds keys. It fetches quotes and builds unsigned transactions; your wallet signs.

Install

npm install @layerhop/sdk
# or: pnpm add @layerhop/sdk / yarn add @layerhop/sdk / bun add @layerhop/sdk

Quickstart

Amounts are always integer strings in base units (100 USDC = "100000000"), never floats.

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

const lh = new LayerHop({ apiKey: process.env.LAYERHOP_API_KEY, integrator: "myapp" });

// 1. Quote every provider; `best` is the highest output for the user.
const { best } = await lh.quote({
  srcChain: "base", srcToken: "USDC", amount: "100000000",
  dstChain: "solana", dstToken: "SOL",
  sender: "0xYourEvmAddress", recipient: "YourSolanaAddress",
});

// 2. Build the unsigned transaction (EVM txs may include an `approval` to send first).
const tx = await lh.buildTx(best.quoteId);

// 3. Sign and send with your own wallet stack (viem, ethers, wallet adapter...), then report it.
//    const hash = await wallet.sendTransaction(tx);
//    await lh.reportSubmitted(best.quoteId, hash);

// 4. Track until filled / refunded / failed.
//    for await (const s of lh.watch(best.provider, hash)) console.log(s.state);

Errors are thrown as LayerHopApiError with a stable code (see the error catalog):

try {
  await lh.buildTx(quoteId);
} catch (e) {
  if (e instanceof LayerHopApiError && e.code === "QUOTE_EXPIRED") {
    // re-quote
  }
}

API

| Method | Endpoint | What | |---|---|---| | quote(params) | GET /v1/quote | Every successful quote, best for the user first. | | buildTx(quoteId) | POST /v1/orders | The unsigned transaction for a quote (EvmTx or SvmTx). | | submit(quoteId, signedTx) | POST /v1/orders/submit | Solana txs with submitViaApi: send the signed tx through LayerHop. | | reportSubmitted(quoteId, txHash) | POST /v1/orders/{quoteId}/submitted | Tell LayerHop the tx was broadcast. | | simulate(quoteId) | POST /v1/simulate | Dry-run the tx (EVM eth_call + gas, Solana simulateTransaction). | | listOrders(params) | GET /v1/orders | Orders from or to an address, newest first. | | status(provider, id) | GET /v1/orders/{provider}/{id} | Order status. | | watch(provider, id, opts?) | polls status | Async generator yielding each state change until final. | | serviceStatus() | GET /v1/status | Platform status (status.layerhop.com): components, 90-day uptime, incidents. | | checkout.create / get / list / expire / quote / stream | /v1/checkout/sessions | Checkout sessions ("pay with any token"). | | checkout.products.* | /v1/checkout/products | Fixed-price products for payment buttons and /buy/{id} links. | | checkout.refunds.create(sessionId, params?) / .list(sessionId) | /v1/checkout/sessions/{id}/refunds | Refund a paid session from your own wallet (build, sign, report). | | invoices.create / get / list / update / send / void | /v1/invoices | Invoices emailed to a customer and paid through checkout (API key). | | invoices.publicView(id) / invoices.pay(id) | /v1/invoices/{id}/public, /pay | The customer's side (public). | | subscriptions.create / get / list / update / cancel / pause / resume / invoices | /v1/subscriptions | Recurring billing: an invoice emailed every period (API key). | | depositAddresses.create / get / list / refresh / disable / simulate | /v1/deposit-addresses | Deposit addresses (beta): your user sends tokens to an address, no wallet connection (API key). |

Invoices and refunds

const lh = new LayerHop({ apiKey: process.env.LAYERHOP_API_KEY });

// Bill a customer: emailed from [email protected], paid at layerhop.com/invoice/{id}.
const invoice = await lh.invoices.create({
  customerEmail: "[email protected]",
  lineItems: [{ description: "Design work", quantity: 2, unitAmount: "500000000" }], // 2 × 500 USDC
  settleChain: "base", settleToken: "USDC", recipient: "0xYourPayoutAddress",
  send: true,
});

// Bill every month: LayerHop emails each period's invoice; unpaid → past_due, reminders, cancel after 7 days.
const sub = await lh.subscriptions.create({
  customerEmail: "[email protected]", interval: "month", description: "Pro plan",
  amount: "49000000", settleChain: "base", settleToken: "USDC", recipient: "0xYourPayoutAddress",
});
await lh.subscriptions.cancel(sub.id, { atPeriodEnd: true });

// Refund a paid session from your wallet (non-custodial): build, sign, report.
const { refund, quote } = await lh.checkout.refunds.create("cs_...", { amount: "10000000", reason: "Partial refund" });
const tx = await lh.buildTx(quote.quoteId);            // sign and broadcast from quote.from
await lh.reportSubmitted(quote.quoteId, "0xTxHash");   // the refund completes when the order fills

Deposit addresses (beta)

// Your user sends USDC on Base to da.address; USDC arrives on Arbitrum. Each deposit is an order.
const da = await lh.depositAddresses.create({
  srcChain: "base", srcToken: "USDC", dstChain: "arbitrum", dstToken: "USDC",
  recipient: "0xUserOnArbitrum", refundTo: "0xUserOnBase",
});
await lh.depositAddresses.refresh(da.id);                                 // "I sent it": check now
const { deposits } = await lh.depositAddresses.get(da.id);               // orders with depositAddressId
await lh.depositAddresses.simulate(da.id, { amount: "25000000" });       // test keys only

Options for new LayerHop(options): baseUrl (default https://api.layerhop.com), apiKey, channel, integrator, integratorFeeBps, fetch, streaming ("auto" | "fetch" | "xhr": how Server-Sent Events streams are read; auto falls back to XMLHttpRequest where fetch can't stream, as in React Native).

The package also exports the chain and token registry (CHAINS, getChain, TOKENS, findToken, SOLANA_CHAIN_ID, EVM_NATIVE, SOL_NATIVE) and all request/response types.

Full reference: https://docs.layerhop.com/sdk.

Related packages

• @layerhop/react — React hooks (useQuote, useSwap, ...).
• @layerhop/widget — embeddable swap widget.
• @layerhop/cli — command line.
• @layerhop/mcp — MCP server for AI agents.

License

MIT