Skip to main content

How SWAPS Works

SWAPS turns marketplace inventory and user intent into visible give/get trade opportunities. Partners do not need to operate matching infrastructure or expose multi-party coordination details to users.

Partner Flow​

  1. Load marketplace inventory with POST /api/v2/partners/inventory/bulk.
  2. Keep live wallet inventory current with POST /api/v2/inventory/update from the widget or trusted backend flows.
  3. Submit specific card wants with POST /api/v2/wants or import them in bulk with POST /api/v2/partners/wants/bulk.
  4. Read available swaps with GET /api/v2/swaps/{walletAddress}.
  5. Read For You recommendations with GET /api/v2/explore/{walletAddress}. Recommendations are availability-checked before they are returned.
  6. Accept a swap with POST /api/v2/swaps/{swapId}/accept. SWAPS prepares the user approval or delegation transaction for the wallet to sign.
  7. Submit exactly one proof to POST /api/v2/blockchain/trades/broadcast: a transactionHash after Ethereum, Base, or Solana wallet broadcast, or a base64 signedTransaction for SWAPS to relay an eligible Solana approval, delegation, revoke, or refund.
  8. SWAPS verifies the approval state, coordinates settlement when all required approvals are ready, and sends webhooks as state changes.

What Users See​

The user-facing model is simple:

  • What the user gives.
  • What the user gets.
  • Whether the opportunity is available, arranging, complete, or failed.
  • A wallet transaction that approves the asset required for the selected trade.

The widget and API hide participant routing, internal scoring inputs, and settlement coordination details.

What Partners See​

Partners get a stable V2 product contract:

  • Tenant-scoped server keys for backend imports.
  • Publishable keys plus HMAC user headers for widget/browser calls.
  • Clear inventory, wants, swaps, For You, accept, broadcast, readiness, and webhook endpoints.
  • Sanitized webhook payloads with public trade state and asset metadata.
  • Readiness checks that show whether the tenant has enough indexed state and live opportunities for launch traffic.

What SWAPS Handles​

SWAPS handles availability checks, stale-state rejection, one-signature approval/delegation preparation, broadcast proof recording, settlement readiness checks, state transitions, and webhook delivery. Assets remain in the user's wallet until settlement. SWAPS cannot move a user's asset without the required wallet approval.