Product Contract

This is the current V2 product contract exposed by the live API and widget.

User Model

Users express exact card-level wants. A want is a wallet plus a specific targetNftId; collection-wide wants, trait substitutions, and open-ended price bids are outside the current V2 contract.

The widget presents each actionable opportunity as:

• what the user gives
• what the user gets
• current status
• confidence and completion context

Coordination details stay behind the API boundary. Partners and users do not need to model the marketplace-wide route.

Primary Endpoints

• POST /api/v2/inventory/update
• POST /api/v2/wants
• GET /api/v2/wants/{walletAddress}
• DELETE /api/v2/wants/{wantId}
• GET /api/v2/swaps/{walletAddress}
• GET /api/v2/explore/{walletAddress}
• POST /api/v2/preference-events
• POST /api/v2/swaps/{swapId}/accept
• POST /api/v2/swaps/{swapId}/pass
• POST /api/v2/blockchain/trades/broadcast
• GET /api/v2/trending

Server-side partner ingestion uses:

• POST /api/v2/partners/inventory/bulk
• POST /api/v2/partners/wants/bulk
• GET /api/v2/partners/readiness
• GET /api/v2/analytics/overview

Widget Embed

The widget is configured from data-* attributes on the script tag. It does not require a custom HTML element.

<script
  src="https://www.swapsapi.com/widget/widget.js"
  data-api-key="pk_live_your_key"
  data-user-id="HaGvQgaU8NyjyDc7BFu47aZQYjRCTLGqeQeCNP9SSdiN"
  data-user-signature="hmac_hex"
  data-user-timestamp="1710590400"
  data-blockchain="solana"
></script>

data-blockchain accepts exactly solana, ethereum, or base. The base value uses the EVM wallet path on the tenant's configured Base network.

For publishable-key calls, the signed widget user is the wallet identity. If a route or body wallet differs from the HMAC-verified user, SWAPS uses the verified user.

See Widget Integration for the full embed contract and auth refresh flow.

Decisions

POST /api/v2/swaps/{swapId}/accept prepares a user-signed approval or delegation transaction. Submit exactly one proof to POST /api/v2/blockchain/trades/broadcast: use transactionHash after an Ethereum, Base, or Solana wallet broadcast, or use the base64 signedTransaction for SWAPS to relay an eligible Solana approval, delegation, revoke, or refund. Base hash submissions must declare blockchain: base.

POST /api/v2/swaps/{swapId}/pass dismisses the visible opportunity without cancelling the underlying want.