Local development & CI

layerhop dev runs a mock LayerHop API on your machine, so you can build and test an integration with no account, no API key, no network and no funds. It answers the core routes with the same JSON shapes as https://api.layerhop.com, which means the SDKs, the CLI and your own HTTP code work against it unchanged. In CI, the setup-layerhop GitHub Action starts it for you. For a hosted sandbox with your dashboard, webhooks endpoints and logs, use test mode instead.

How do I start the mock API?#

npx @layerhop/cli dev
# LayerHop mock API on http://127.0.0.1:8787
#   export LAYERHOP_API_URL=http://127.0.0.1:8787

Point your code at it:

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

const lh = new LayerHop({ baseUrl: process.env.LAYERHOP_API_URL ?? "https://api.layerhop.com" });
const { best } = await lh.quote({
  srcChain: "base", srcToken: "USDC", amount: "100000000",
  dstChain: "solana", dstToken: "SOL",
  sender: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  recipient: "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
});
const tx = await lh.buildTx(best.quoteId);          // a placeholder: never broadcast it
await lh.reportSubmitted(best.quoteId, `0x${"ab".repeat(32)}`);
for await (const s of lh.watch("mock", `0x${"ab".repeat(32)}`, { intervalMs: 500 })) console.log(s.state);

The Python, Go and Rust SDKs take the same base URL, and every CLI command honours LAYERHOP_API_URL. The server allows any origin (CORS), so a local front end can call it from the browser.

What does the mock API cover?#

Anything else (checkout, invoices, subscriptions, deposit addresses, limit orders, the dashboard) returns NOT_FOUND with a pointer to test mode, which covers every endpoint. Errors use the real shape, { "error": { code, message, requestId, docsUrl } }.

How do I test refunds and failures?#

The last digits of amount pick the outcome, exactly like test mode's magic amounts:

How do I receive webhooks locally?#

npx @layerhop/cli dev --webhook-url http://localhost:3000/api/layerhop-webhooks --secret whsec_dev_only_secret

Each reported order sends order.submitted and then order.filled, order.refunded or order.failed, signed with the LayerHop-Signature header exactly like real deliveries, so your verification code runs unchanged (see Webhooks). POST /v1/webhooks/trigger with {"type":"order.filled"} sends a sample on demand.

How do I use it in GitHub Actions?#

The layerhop/setup-layerhop action starts the mock API in the background, waits until it answers, and exports LAYERHOP_API_URL (and LAYERHOP_WEBHOOK_SECRET when you pass a webhook URL) for the following steps:

name: Integration tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - uses: layerhop/setup-layerhop@v1
        with:
          fill-after: "1"                                    # orders finish in 1 second
          webhook-url: http://localhost:3000/api/layerhop-webhooks   # optional
      - run: npm ci
      - run: npm test   # reads process.env.LAYERHOP_API_URL

layerhop dev ships in the first @layerhop/cli release after 0.6.0, and the action is published as layerhop/setup-layerhop with it.

Inputs: port (8787), cli-version (latest), fill-after (1), webhook-url, webhook-secret (random when empty), fork and fork-chains, timeout (60). Outputs: api-url, webhook-secret. Without the action, any CI can run npx @layerhop/cli dev --port 8787 & and poll /v1/health.

Can I test against forked mainnet state?#

Yes, for EVM chains. With Foundry installed (curl -L https://foundry.paradigm.xyz | bash && foundryup), --fork starts one Anvil fork per chain next to the mock API:

npx @layerhop/cli dev --fork --fork-chains base,arbitrum
# Anvil fork of base (chain id 8453) on http://127.0.0.1:8545
# Anvil fork of arbitrum (chain id 42161) on http://127.0.0.1:8546

Each fork keeps the real chain id and copies mainnet state on demand, and Anvil gives you prefunded test accounts. Use the forks to exercise wallet connection, signing and token-approval code against real token contracts without spending anything. GET /v1/health lists the running forks. The mock API's transactions stay placeholders: forks don't make provider routes executable locally, because the bridges and solvers behind them only run on mainnet.

Forks read state through public RPCs (rate limited). Set your own per chain with LAYERHOP_FORK_RPC_<CHAIN>, for example LAYERHOP_FORK_RPC_BASE=https://base-mainnet.example/your-key. Without Anvil, --fork prints how to install it and starts the mock API alone.

Can I import the API into Postman, Insomnia or Bruno?#

Yes. The Postman collection is generated from the OpenAPI spec with a folder per API area, example requests and example responses. In Postman choose Import → Link and paste https://docs.layerhop.com/layerhop.postman_collection.json; Insomnia and Bruno import the same file. Set the collection variables apiKey (an lh_test_ key) and baseUrl (https://api.layerhop.com, or http://127.0.0.1:8787 for layerhop dev). Code generators can use the spec itself: openapi.yaml or openapi.json.

What's not included yet?#

• A local Solana validator. --fork covers EVM chains only. Solana flows run against the mock API's placeholder transactions or test mode.
• A testnet faucet. LayerHop's providers are mainnet-only, so there is no LayerHop testnet to fund. A faucet would also need wallets funded by LayerHop, which is an owner decision that hasn't been made. Use test mode or layerhop dev instead: neither needs funds.