Skip to main content

Trust Model

SWAPS is non-custodial. Users keep assets in their wallets until settlement.

Keys​

Server endpoints require a secret server key. Browser and widget endpoints use a publishable key plus signed widget-user HMAC headers:

  • X-Swaps-User-Id
  • X-Swaps-User-Signature
  • X-Swaps-User-Timestamp

The HMAC message is swaps-user:{userId}:{timestamp}. Signatures expire after 24 hours, with a 5-minute future timestamp tolerance.

User Approval​

Accepting a swap does not transfer the asset immediately. It prepares the approval or delegation transaction the user signs in their wallet.

  • Ethereum: token-scoped ERC-721 approval for the offered NFT.
  • Solana: delegation for the offered NFT, with separate paths for standard NFTs, pNFTs when enabled, and compatible Core assets.

Submit exactly one proof to POST /api/v2/blockchain/trades/broadcast. Use transactionHash after an Ethereum, Base, or Solana wallet broadcast. For an eligible Solana approval, delegation, revoke, or refund, the widget may instead submit the base64 signedTransaction for SWAPS to relay. SWAPS verifies confirmation and the operation-level chain proof before advancing state.

Settlement​

When all required approvals are ready, SWAPS executes settlement and reconciles status automatically. Settlement is all-or-nothing: either every transfer succeeds or the trade does not complete.

Revocation​

Users can prepare a revoke transaction with POST /api/v2/delegations/{nftId}/revoke. Cancelling a want also cancels the active signed intent for that give/get pair in the SWAPS read model.

Refunds​

When one approved Solana route completes, other approved routes for the same offered card are retired. If a retired sibling route has an unused SWAPS completion-fee hold, it appears in GET /api/v2/delegations/refunds/{walletAddress} and the user can prepare a refund transaction with POST /api/v2/delegations/{nftId}/refund. The widget shows these in Activity as unused fees ready to claim. Refunds reclaim the unused SWAPS completion fee for that give/get intent; Solana network fees are not refundable.

Webhooks​

Outbound webhooks are HMAC signed and use partner-safe payloads. Webhooks do not include internal discovery metadata.