Docs/API

FiberTracebox integration surface

The app runs fully in sandbox mode for deterministic demos and can also connect to a Fiber Network Node JSON-RPC endpoint for live payment dry-runs or explicitly enabled live sends.

Live API base

https://fibertracebox.online

API Examples

Health

curl https://fibertracebox.online/api/health

Run scenario

curl -X POST https://fibertracebox.online/api/scenarios/run -H 'content-type: application/json' -H "x-api-key: $FIBERTRACEBOX_API_KEY" -d '{"scenario":"route-capacity"}'

Live dry-run

curl -X POST https://fibertracebox.online/api/traces -H 'content-type: application/json' -H "x-api-key: $FIBERTRACEBOX_API_KEY" -d '{"invoice":"<fiber-invoice>","dryRun":true}'

Replay trace

curl -X POST https://fibertracebox.online/api/traces/<traceId>/replay -H "x-api-key: $FIBERTRACEBOX_API_KEY"

Verify live fix

curl -X POST https://fibertracebox.online/api/traces/<traceId>/verify -H 'content-type: application/json' -H "x-api-key: $FIBERTRACEBOX_API_KEY" -d '{"invoice":"<fresh-invoice>"}'

Markdown report

curl https://fibertracebox.online/api/traces/<traceId>/report?format=markdown

CLI Examples

Use these from the project folder while developing locally.

npm run cli -- health

npm run demo:judge

npm run cli -- scenario run route-capacity

npm run cli -- live <fiber-invoice>

npm run cli -- trace list

npm run cli -- replay <traceId>

npm run cli -- verify <failed-live-trace-id> <fresh-invoice>

npm run cli -- report <traceId> --format markdown

Optional linked binary

Run npm run build:cli, then npm link once if you want the global fibertracebox command.

npm run build:cli

npm link

fibertracebox health

fibertracebox scenario run route-capacity

fibertracebox live <fiber-invoice>

fibertracebox trace list

CLI Setup

The local CLI reads FIBERTRACEBOX_API_URL and FIBERTRACEBOX_API_KEY from your shell environment. Set the API URL to this deployment when using the live link. If write protection is enabled, export the same API key used by the server before running write commands.

export FIBERTRACEBOX_API_URL=https://fibertracebox.online

export FIBERTRACEBOX_API_KEY=<your-api-key>

Sandbox Mode

Sandbox mode simulates Fiber payment failures using deterministic routes, channel capacity, peer state, fees, timeouts, retries, and liquidity conditions. Use it for repeatable demos, testing, and debugging without connecting to a live Fiber node.

Optional Fiber RPC Mode

Fiber RPC mode connects FiberTracebox to a Fiber Network Node. The app checks node health and channel state, then creates dry-run or live payment traces from invoices. Live sends require explicit server-side enablement.

Live Node Boundaries

Run your Fiber node separately and keep its JSON-RPC endpoint private.
Use valid invoices, connected peers, open channels, and sufficient liquidity.
Replay-to-Fix executes controlled strategies for sandbox traces. Live traces receive suggested fix plans whose outcomes are recorded only through FNN Live Verification.
Live Verification links a corrected, server-enforced FNN dry-run when a receiver or fresh invoice is available.
Use the Live Fiber RPC panel for FNN-backed checks and sandbox scenarios for synthetic demos.

Evidence Bundles

Reports include trace timelines, failure fingerprints, replay evidence, and recommended fixes. Markdown and JSON exports can be generated from each trace detail page or through the API.

The repository proof bundle is a real local Fiber testnet live send from Node1 (sender) to Node2 (receiver), captured on 2026-07-04. The hosted deployment currently uses the Node1 environment, but its current pubkey differs from the historical capture.

Capabilities

Sandbox failure simulation for route, capacity, peer, fee, timeout, and liquidity cases.
Fiber RPC health checks, invoice dry-runs, and live-send traces when enabled.
Failure diagnosis with fingerprints, likely causes, and suggested fixes.
Replay-to-Fix recommendations for finding the smallest successful change.
Linked Live Verification dry-runs for failed Fiber traces when a receiver is available.
Markdown and JSON report exports for sharing trace evidence.
Dashboard, API, CLI, and SDK surfaces for integrating payment diagnostics.