Quickstart

Requirements

• Node.js 20 or newer.
• The repository dependencies installed with npm.
• Docker and the sibling Loavix workspace, which provides a merchant Fiber testnet node.
• A terminal and a browser.

Run the resolver

cd ../loavix
docker compose --profile fiber up -d fiber

cd ../fiber-offers
npm install
npm run verify
npm run dev

Open the console at http://localhost:8787. The status should report Fiber RPC, and diagnostics should show automatic workers enabled.

Create a test offer

curl -X POST http://localhost:8787/demo/offers \
  -H 'content-type: application/json' \
  -d '{
    "username": "coffee",
    "description": "Coffee checkout",
    "pricing_type": "fixed",
    "amount": "1000",
    "assets": [{ "asset_type": "ckb", "symbol": "CKB" }]
  }'

Copy the offer_id from the response. The resolver also returns a payment link, two QR URLs, an encoded offer, and the Fiber Address coffee@localhost:8787.

Check payment readiness

Readiness validates the exact amount and asset without creating an invoice. Call it before enabling the final wallet confirmation step.

curl -X POST http://localhost:8787/offers/0x.../check \
  -H 'content-type: application/json' \
  -d '{
    "amount": "1000",
    "asset": { "asset_type": "ckb", "symbol": "CKB" }
  }'

A ready response includes next_action: "request_invoice" and live merchant-node details. Route confidence belongs in the payer wallet, which can dry-run the returned invoice against its own node before sending.

Request a fresh invoice

curl -X POST http://localhost:8787/offers/0x.../invoice \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: checkout-order-42' \
  -d '{
    "amount": "1000",
    "asset": { "asset_type": "ckb", "symbol": "CKB" }
  }'

The response contains a new invoice and resolution ID. Repeat the same request with the same idempotency key to prove it returns the original resolution instead of issuing another invoice.