Skip to docs content
Fusion Docs
Book a Call
Home
What Is Fusion?How Fusion WorksStandard vs Shielded RoutesAtomic Settlement Guarantee
QuickstartWallet App Integration
Solver OverviewCoordinator Overview
Supported Chains Overview
Security ModelTrust AssumptionsThreat Model
Intent SchemaChains and TimelocksAPI and WebSocket OverviewWebSocket Events
Whitepaper and Research
Home
Reference

API and WebSocket Overview

Wire-level map of every REST endpoint and Socket.IO event the backend exposes.

This page is a map of Fusion's current backend surfaces.

It is intentionally conservative:

  • it describes endpoints and events that are actually exposed by the backend
  • it calls out internal and test-only paths separately
  • it does not assume every helper used internally is already mirrored by a server event

Health and discovery

  • GET /api/health
  • GET /api/chains
  • GET /api/config/htlc-addresses

Use these before enabling route-specific UI. GET /api/chains is especially useful because the backend exposes whether a chain is enabled and operational in the current runtime.

Public intent signing and submission

  • POST /api/intents/get-nonce
  • POST /api/intents/get-domain
  • POST /api/intents/submit
  • GET /api/intents/:intentId
  • GET /api/intents/:id/htlc-params

Common status values returned by the backend:

  • proofs_pending
  • proofs_verified
  • matched
  • waiting_for_source_lock
  • executing
  • completed
  • failed

Gasless EVM source-lock flow

  • GET /api/intents/:intentId/permit2-params
  • POST /api/intents/:intentId/relay-permit

The backend allocates a Permit2 nonce per intent and rejects the flow if the intent is not ready, the proof state is incomplete, or the deadline has already expired.

Cross-family session APIs

Cross-family routes use session endpoints instead of the standard EVM source-lock path. The endpoints below are the current set for the Midnight integration — the same session-based shape will apply to other non-EVM chain families as they come online:

  • POST /api/midnight/source-lock/sessions
  • POST /api/midnight/source-lock/sessions/:sessionId/deploy-submitted
  • POST /api/midnight/source-lock/sessions/:sessionId/lock-submitted
  • POST /api/midnight/refund/prepare
  • POST /api/midnight/refund/sessions/:refundSessionId/submitted
  • GET /api/midnight/balance

Other surfaces you may see

The following endpoints exist but are intended for testing or internal flows. Do not treat them as the stable public integration surface:

  • POST /api/intents/submit-e2e
  • GET /api/intents/:id/preimage
  • GET /api/intents/pending/:address

Socket.IO events

The backend WebSocketServer currently supports:

  • client emits: subscribe:intent
  • client emits: unsubscribe:intent
  • client emits: subscribe:all
  • client emits: unsubscribe:all
  • client emits: ping
  • server emits: intent:status
  • server emits: intent:proof
  • server emits: intent:new
  • server emits: intent:status_changed
  • server emits: intent:proof_changed
  • server emits: intent:removed
  • server emits: intent:not_found
  • server emits: mempool:stats
  • server emits: pong
  • server emits: error

See WebSocket Events for full payload schemas.

One current mismatch

Some clients listen for an intent:settlement_proof event. As of today, that event is not emitted by the backend WebSocket server. Shielded settlement still works; the event just isn't part of the current public WebSocket contract until the server implementation adds it.

Suggested integration order

Start with the core flow and add extras as needed:

  1. health and chain discovery
  2. nonce and domain fetch
  3. intent submit
  4. WebSocket subscription for status
  5. Permit2 flow if you need gasless EVM source locks
  6. cross-family session endpoints only if you are explicitly taking on a cross-family route

Related docs: