Starter templates

LayerHop's starter templates are small, complete projects you can clone, deploy to Vercel in one click or open in StackBlitz. They live in github.com/layerhop/examples, and each one is standalone: it installs the published @layerhop/sdk, @layerhop/react and @layerhop/widget packages from npm, so you can copy a folder anywhere and it still builds. TypeScript strict throughout, a .env.example for configuration, no keys in the browser.

Which template should I start from?#

Use a template#

Copy one folder with degit, configure it, run it:

npx degit layerhop/examples/nextjs-swap my-swap
cd my-swap
cp .env.example .env.local
npm install
npm run dev

Each template's README has a Deploy with Vercel button (it asks for the environment variables the template needs) and an Open in StackBlitz link that runs it in the browser.

What every template does the same way#

• Users sign in their own wallets. Templates build unsigned transactions and let the browser wallet sign them. Nothing signs on a server, and nothing sends a transaction by itself. See Non-custodial by design.
• Secrets stay server-side. API keys and webhook signing secrets come from environment variables and are only read in server code.
• Test mode first. The checkout and deposit address templates work with a test key (lh_test_…): sandboxed sessions and addresses, sample webhooks, no funds moved. See Test mode.
• Webhooks are verified. Handlers check the LayerHop-Signature header on the raw body and deduplicate on event.id, as described in Webhooks.
• You earn as a partner. Set your partner id (integrator) and swaps through the template carry your fee on top of LayerHop's. See Earn fees as a partner.

Template details#

Next.js swap page#

A single page with chain and token pickers, a live best quote (route, time, LayerHop fee and your partner fee), and a Swap button that runs the useSwap state machine: build, approve the exact amount only when the allowance is too low, send, then track until the order is filled. EVM wallets connect through RainbowKit (browser extensions out of the box, WalletConnect with a free project id) and Solana wallets through the wallet adapter; Solana transactions with submitViaApi are signed only and submitted through LayerHop. Environment: NEXT_PUBLIC_LAYERHOP_INTEGRATOR, NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID, NEXT_PUBLIC_SOLANA_RPC_URL.

Next.js checkout#

A product page posts to a route handler that calls lh.checkout.create(...) with your secret key, then redirects to the hosted page or to an on-site page that embeds <LayerHopCheckout sessionId>. The webhook route verifies the signature, ignores duplicate deliveries and fulfils on checkout.session.completed; the success page reads the session status from the API. Environment: LAYERHOP_API_KEY, LAYERHOP_WEBHOOK_SECRET, MERCHANT_RECIPIENT, plus optional settlement chain and token. Background: Checkout and Embedded checkout.

Deposit address backend#

POST /users/:userId/deposit-address creates one reusable address per user (label = the user id), and POST /webhooks/layerhop credits the user once per filled order, matched by depositAddressId. A test-mode route records fake deposits so you can try the loop end to end, and the Dockerfile runs it with a volume for the JSON store. Background: Deposit addresses.

Widget embed#

index.html is the no-build version: a <div data-layerhop-widget> with data attributes and the pinned embed.js script tag. react.html shows the <LayerHopWidget> component with typed props and event callbacks. Background: Embed the widget and the widget reference.

AI agent#

Two AI SDK tools, get_quote and build_unsigned_transaction, wrap lh.quote and lh.buildTx. The script prints the agent's answer, the unsigned transaction (with the approval to send first, if any) and a prefilled swap link. npm run demo calls the tools without a model. For MCP clients, use the hosted server in AI agents instead.