Wants Submission

Register a card want for a wallet. Current V2 wants use a specific targetNftId intent: give one owned NFT for that target NFT if SWAPS can coordinate a route.

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: user_123" \
  -H "X-Swaps-User-Signature: <hmac_signature>" \
  -H "X-Swaps-User-Timestamp: <unix_timestamp>" \
  -d '{"walletAddress":"0x1111111111111111111111111111111111111111","targetNftId":"0x3333333333333333333333333333333333333333:5"}'

Cancel a standing want with DELETE /api/v2/wants/{wantId}. Cancelling a want also cancels the active signed intent for that give/get pair.

Example response:

{
  "success": true,
  "want": {
    "id": "want_tenant_123_0x1111111111111111111111111111111111111111_0x3333333333333333333333333333333333333333:5",
    "walletAddress": "0x1111111111111111111111111111111111111111",
    "targetNft": {
      "id": "0x3333333333333333333333333333333333333333:5",
      "name": "Mew Holo",
      "image": "https://cdn.example/mew.png",
      "collection": "Pokemon Promo"
    },
    "status": "matched",
    "matchCount": 1,
    "createdAt": "2026-05-05T10:35:00.000Z"
  },
  "immediateMatches": [],
  "message": "Found 0 swaps for this item"
}

Partner backends can import card wants for many users with POST /api/v2/partners/wants/bulk.

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":"0x1111111111111111111111111111111111111111","wantedNftIds":["0x3333333333333333333333333333333333333333:5"]}]}'

Bulk wants also accepts a flat wants array of { "walletAddress", "targetNftId" } objects.

Example response:

{
  "success": true,
  "walletsProcessed": 1,
  "wantsProcessed": 1,
  "swapsDiscovered": 0,
  "message": "Imported 1 card wants. SWAPS is working on matching them."
}