Solver Onboarding

External solvers do not use a separate SW4P product surface. They participate through the same intent and auction model that powers the canonical API.

Required Surfaces

Third-party solvers need these backend surfaces:

POST /sdk/v2/filler/register
POST /sdk/v2/auction/:intentId/quote
GET /sdk/v2/auction/:intentId
GET /sdk/v2/auctions/open
POST /sdk/v2/auction/:intentId/confirm-fill
GET /sdk/v2/auctions/feed for the WebSocket event stream

The TypeScript and Rust SDKs wrap the REST auction surfaces above. The WebSocket feed is consumed directly at /sdk/v2/auctions/feed.

Registration

json

{
  "name": "example-solver",
  "apiKey": "sk_solver_...",
  "supportedChains": ["BASE", "SOLANA"],
  "supportedTokens": ["USDC", "SOL"]
}

The backend stores a hashed API key and tracks solver reputation, fill counts, and total volume.

WebSocket Feed

Connect to:

text

GET /sdk/v2/auctions/feed

The first message must be an auth payload:

json

{ "api_key": "sk_solver_..." }

After authentication, the feed emits these event types:

`auction_opened`

json

{
  "type": "auction_opened",
  "auction_id": "auc_123",
  "intent_id": "int_123",
  "house_baseline_output": 100000000,
  "deadline": 1760000000
}

`quote_received`

json

{
  "type": "quote_received",
  "auction_id": "auc_123",
  "quote_count": 3,
  "best_output": 100500000
}

`auction_closed`

json

{
  "type": "auction_closed",
  "auction_id": "auc_123",
  "winner_filler_id": "solver_abc",
  "winning_output": 100750000,
  "fill_deadline": 1760000300
}

Quote Rules

External quotes must beat the house baseline on output_amount.
Fillers authenticate with filler_id plus filler_api_key.
Reputation gating is enforced server-side.
A winning filler still has to confirm the fill through the canonical confirm-fill surface.

Metrics Operators Watch

The control-plane metrics for solver participation are:

solver_auctions_opened_total
solver_quotes_received_total
solver_auctions_closed_total
solver_house_wins_total
solver_external_wins_total
solver_fills_confirmed_total
solver_fill_expired_total

These roll up into quote density, external win, and fill confirmation signals in the monitoring stack and operator runbooks.