Skip to main content

Quickstart

Follow these steps to integrate the current V2 product API.

Create a Tenant​

For human onboarding, use the hosted SWAPS signup. Hosted signup intentionally offers Ethereum and Solana only. Choose a launch tenant or free sandbox, complete the security verification, and copy the server key, publishable key, and widget HMAC secret when they are shown.

The signup API is not a static copy-paste request. POST /api/v2/signup/free and POST /api/v2/signup/launch require a single-use Cloudflare Turnstile token for the signup action. If you embed tenant creation in your own browser UI, first read GET /api/public/forms/config, render Turnstile with the returned public site key and action, then submit that browser-generated token as captchaToken. Never hard-code or reuse a token.

Choose the chain deliberately. Hosted self-serve signup currently provisions Ethereum or Solana tenants. Solana card marketplaces should select Solana; Ethereum marketplaces should select Ethereum. Base is supported by the widget and settlement runtime, but it is not a hosted self-serve signup option. Base partners need assisted launch provisioning for a Base-configured tenant; do not create a free Ethereum tenant expecting to switch it to Base later. For Solana Metaplex Core launch tenants, send "assetStandard":"Core" with "minParticipants":6. Core loops with 2-6 participants use compact Core settlement and do not require an address lookup table. For Solana pNFT launch tenants, send "assetStandard":"ProgrammableNonFungible" with "minParticipants":5. pNFT loops with 2-5 participants require the deployment to have SWAPS_PNFT_ALT_ADDRESS configured with a populated Solana address lookup table for the pNFT execution accounts.

Drop the SWAPS widget into your frontend so users can connect a wallet, choose the card they want, and approve a visible give/get trade from their perspective.

  1. Get your publishable key (pk_live_) and HMAC secret from the dashboard.
  2. Add the widget script to your page. The live widget reads configuration from data-* attributes on the script tag:
<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-theme="dark"
  data-blockchain="solana"
  data-inventory='["GM4zYgkVopM4VPW4mMgbuNn5eVsGyRNVZjJMhFdakh2N"]'
></script>

data-blockchain accepts exactly solana, ethereum, or base. For base, the connected wallet must use the configured Base network.

  1. Your backend signs the widget user with HMAC-SHA256(hmacSecret, "swaps-user:{userId}:{timestamp}"). Use the same wallet address for data-user-id and the HMAC message.
  2. The widget uses V2 endpoints for inventory sync, card wants, swap reads, recommendations, preference events, user signing, broadcast reporting, completion state, and unused-fee refund claims.

See Widget Integration for the complete script-tag contract, HMAC signing flow, global widget API, and common failure cases.

Server-Side Inventory (V2)​

Use sk_live_ secret keys only from your backend, and never embed them in browser or widget code. Widget-capable endpoints use pk_live_ plus HMAC user authentication for browser requests. Some dual-use endpoints also accept a server key from trusted server-side integrations, so server keys are not categorically rejected by those routes.

  1. Obtain a server key from the hosted signup flow or Dashboard → API Keys.
  2. Bulk load current inventory:

Solana card partners should send rich items[] for discovery metadata, but bulk floorPrice is only a seed and can become stale. Production fee quotes use the tenant's configured partner valuation source, such as a verified Insured Value metadata trait or a live partner API, and SWAPS refuses signing when that source cannot be refreshed.

curl -X POST https://www.swapsapi.com/api/v2/partners/inventory/bulk \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"users":[{"walletAddress":"HaGvQgaU8NyjyDc7BFu47aZQYjRCTLGqeQeCNP9SSdiN","items":[{"id":"GM4zYgkVopM4VPW4mMgbuNn5eVsGyRNVZjJMhFdakh2N","name":"Charizard PSA 10","collection":"Pokemon Base Set","floorPrice":500,"currency":"USD"}]}]}'
  1. Check readiness:
curl -H "Authorization: Bearer <API_KEY>" \
  https://www.swapsapi.com/api/v2/partners/readiness
  1. Optionally import card wants at scale:
curl -X POST https://www.swapsapi.com/api/v2/partners/wants/bulk \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -d '{"users":[{"walletAddress":"HaGvQgaU8NyjyDc7BFu47aZQYjRCTLGqeQeCNP9SSdiN","wantedNftIds":["7n7s9XdVTCrQ1KSpqtaZtwfSGBjDih3dnZ6CSVADwQdc"]}]}'

Widget/User Flow (V2)​

Browser requests use pk_live_ plus signed widget-user headers. For publishable-key requests, SWAPS uses the verified header user as the wallet identity.

curl -X POST https://www.swapsapi.com/api/v2/wants \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -H "X-Swaps-User-Id: HaGvQgaU8NyjyDc7BFu47aZQYjRCTLGqeQeCNP9SSdiN" \
  -H "X-Swaps-User-Signature: <hmac_signature>" \
  -H "X-Swaps-User-Timestamp: <unix_timestamp>" \
  -d '{"walletAddress":"HaGvQgaU8NyjyDc7BFu47aZQYjRCTLGqeQeCNP9SSdiN","targetNftId":"7n7s9XdVTCrQ1KSpqtaZtwfSGBjDih3dnZ6CSVADwQdc"}'

Read available swaps with GET /api/v2/swaps/{walletAddress}, recommendations with GET /api/v2/explore/{walletAddress}, and claimable unused fees with GET /api/v2/delegations/refunds/{walletAddress}. For publishable-key widget calls, SWAPS uses the HMAC-verified user as the wallet identity if the route wallet and signed user differ. Accepting a swap prepares a delegation or token-scoped approval transaction for the user to sign.

Submit Wallet Broadcast Proof​

POST /api/v2/blockchain/trades/broadcast accepts exactly one proof form:

  • Use transactionHash after the wallet broadcasts an Ethereum, Base, or Solana transaction. Include "blockchain":"base" for Base; an undeclared EVM hash is inferred as Ethereum.
  • Use signedTransaction when the widget signs an eligible Solana approval, delegation, revoke, or refund without broadcasting it. The value is the base64 signed transaction; SWAPS relays it and verifies confirmation.

Client-submitted proofs can advance only wallet-bound approve, delegate, revoke, and refund operations. A finalize hash is accepted only to reconcile an already-completed loop against its server-recorded settlement hash. Do not submit client-reported create, addParticipant, or execute proofs.

{
  "tradeId": "trade_123",
  "transactionHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "operation": "delegate",
  "blockchain": "base",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "nftId": "0x3333333333333333333333333333333333333333:1"
}
{
  "tradeId": "trade_456",
  "signedTransaction": "AQAAAAAAAA...",
  "operation": "delegate",
  "blockchain": "solana",
  "walletAddress": "HaGvQgaU8NyjyDc7BFu47aZQYjRCTLGqeQeCNP9SSdiN",
  "nftId": "GM4zYgkVopM4VPW4mMgbuNn5eVsGyRNVZjJMhFdakh2N"
}

V1 routes remain mounted only as legacy compatibility. New integrations should use /api/v2/docs, /api/v2/blockchain/docs, and /reference.