Response Examples

These examples reflect the current V2 partner and widget contract. Identifiers are illustrative.

Bulk Inventory

POST /api/v2/partners/inventory/bulk

{
  "success": true,
  "usersProcessed": 2,
  "nftsIndexed": 4,
  "inventoryState": {
    "wallets": 2,
    "opportunities": 1
  },
  "mode": "merge",
  "message": "Merged 2 users with their inventory. Existing inventory was left untouched."
}

Bulk Wants

POST /api/v2/partners/wants/bulk

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

Submit Want

POST /api/v2/wants

{
  "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": [
    {
      "id": "trade_123",
      "youGive": {
        "id": "0x3333333333333333333333333333333333333333:1",
        "name": "Charizard PSA 10",
        "image": "https://cdn.example/charizard.png",
        "collection": "Pokemon Base Set"
      },
      "youGet": {
        "id": "0x3333333333333333333333333333333333333333:5",
        "name": "Mew Holo",
        "image": "https://cdn.example/mew.png",
        "collection": "Pokemon Promo",
        "floorPrice": 1194.315064,
        "currency": "USD",
        "valuation": {
          "amount": 1194.315064,
          "currency": "USD",
          "sourceType": "partner_api",
          "sourceIdentifier": "partner-price-20260528-143000",
          "fetchedAt": "2026-05-28T14:30:00.000Z",
          "freshness": "fresh"
        }
      },
      "confidence": 0.85,
      "alternativeCount": 1,
      "status": "available"
    }
  ],
  "message": "Found 1 swap for this item"
}

Available Swaps

GET /api/v2/swaps/{walletAddress}

{
  "success": true,
  "swaps": [
    {
      "id": "trade_123",
      "youGive": {
        "id": "0x3333333333333333333333333333333333333333:1",
        "name": "Charizard PSA 10",
        "image": "https://cdn.example/charizard.png",
        "collection": "Pokemon Base Set"
      },
      "youGet": {
        "id": "0x3333333333333333333333333333333333333333:5",
        "name": "Mew Holo",
        "image": "https://cdn.example/mew.png",
        "collection": "Pokemon Promo"
      },
      "confidence": 0.85,
      "alternativeCount": 1,
      "estimatedDuration": "2-5 minutes",
      "createdAt": "2026-05-05T10:35:00.000Z",
      "status": "available"
    }
  ],
  "total": 1
}

For You

GET /api/v2/explore/{walletAddress}

{
  "success": true,
  "sections": [
    {
      "id": "available_now",
      "title": "Available now",
      "subtitle": "Trades this wallet can act on now.",
      "items": [
        {
          "id": "explore_123",
          "source": "active_swap",
          "sectionId": "available_now",
          "target": {
            "id": "0x3333333333333333333333333333333333333333:5",
            "name": "Mew Holo",
            "image": "https://cdn.example/mew.png",
            "collection": "Pokemon Promo"
          },
          "confidence": 0.85,
          "reason": "Available based on your active wants.",
          "tradeAvailable": true,
          "action": "open_swap"
        }
      ]
    }
  ],
  "generatedAt": "2026-05-05T10:35:00.000Z"
}

Accept Swap

POST /api/v2/swaps/{swapId}/accept

Solana accept responses return a serialized transaction for the wallet to sign. The network fee, SWAPS completion fee, reusable fee-hold rent reserve, estimated total SOL required, and partner valuation source are separate fields. The rent reserve is reused across the wallet's SWAPS approvals and returned when the final Solana delegation is revoked.

{
  "success": true,
  "status": "awaiting_signature",
  "blockchain": "solana",
  "transaction": {
    "serialized": "AQAAAAAAAA...",
    "message": "Approve SWAPS to trade Charizard PSA 10; this reserves the SWAPS completion fee in SOL",
    "estimatedFee": 5000,
    "networkFeeLamports": 5000,
    "completionFeeLamports": "149289383",
    "completionFeeSol": 0.149289383,
    "swapsFeeLamports": "149289383",
    "swapsFeeSol": 0.149289383,
    "feeBasisPoints": 250,
    "feeQuote": {
      "blockchain": "solana",
      "nativeCurrency": "SOL",
      "receivedNftId": "3JF3sEqM796hk5WFqA6EtmEwJQ9quALszsfJyvXNQKy3",
      "valuationAmount": 1194.315064,
      "valuationCurrency": "USD",
      "valuationSourceType": "partner_api",
      "valuationSourceIdentifier": "partner-price-20260528-143000",
      "valuationFetchedAt": "2026-05-28T14:30:00.000Z",
      "valuationFreshness": "fresh",
      "feeBasisPoints": 250,
      "feeLamports": "149289383",
      "feeSol": 0.149289383
    },
    "feeHoldAddress": "4Ss5JMkXAD9Z7cktFEdrqeMuT6jGMF1pVozTyPHZ6zT4",
    "feeHoldAlreadyExists": false,
    "feeHoldRentReserveLamports": 890880,
    "feeHoldRentReserveSol": 0.00089088,
    "estimatedTotalLamportsRequired": 150185263,
    "estimatedTotalSolRequired": 0.150185263
  },
  "message": "Sign once to approve this trade. The transaction reserves the SWAPS fee in SOL; any first-time fee-hold rent reserve stays reusable and is returned when the final Solana delegation is revoked."
}

Ethereum and Base accept responses return an ordered EVM call plan. EIP-5792-capable wallets batch once; fallback wallets may require sequential confirmations. The transaction object mirrors the first call. This illustrative payload uses synthetic identifiers.

{
  "success": true,
  "status": "awaiting_signature",
  "blockchain": "ethereum",
  "calls": [
    {
      "to": "0x1111111111111111111111111111111111111111",
      "data": "0x095ea7b3000000000000000000000000...",
      "value": "0",
      "gasLimit": "65000"
    },
    {
      "to": "0x2222222222222222222222222222222222222222",
      "data": "0x8340f549000000000000000000000000...",
      "value": "149289383000000000",
      "gasLimit": "120000"
    }
  ],
  "tradeSeed": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "chainId": 11155111,
  "transaction": {
    "serialized": "",
    "message": "Approve SWAPS to trade Charizard PSA 10; this escrows the SWAPS completion fee in ETH (refundable until the swap completes)",
    "estimatedFee": 65000,
    "to": "0x1111111111111111111111111111111111111111",
    "data": "0x095ea7b3000000000000000000000000...",
    "value": "0",
    "gasLimit": "65000",
    "completionFeeWei": "149289383000000000",
    "completionFeeEth": 0.149289383,
    "feeBasisPoints": 250,
    "feeQuote": {
      "blockchain": "ethereum",
      "nativeCurrency": "ETH",
      "receivedNftId": "0x3333333333333333333333333333333333333333:5",
      "valuationAmount": 1194.315064,
      "valuationCurrency": "USD",
      "valuationSourceType": "partner_api",
      "valuationSourceIdentifier": "partner-price-20260528-143000",
      "valuationFetchedAt": "2026-05-28T14:30:00.000Z",
      "valuationFreshness": "fresh",
      "feeBasisPoints": 250,
      "feeWei": "149289383000000000",
      "feeEth": 0.149289383
    }
  },
  "message": "Use the returned call plan to approve this card and reserve the completion fee."
}

Broadcast Proof

POST /api/v2/blockchain/trades/broadcast

{
  "success": true,
  "message": "Transaction recorded and pending on-chain confirmation",
  "blockchain": "ethereum",
  "transactionHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "explorerUrl": "https://sepolia.etherscan.io/tx/0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "status": "pending_confirmation",
  "transactionStatus": "pending",
  "confirmations": 0,
  "tradeLoopStatus": "pending_confirmation"
}

Refund Retired Intent Fee

GET /api/v2/delegations/refunds/{walletAddress}

Solana list items report the exact completion-fee refund in lamports and a SOL display value. This synthetic example uses the loop-scoped pNFT escrow refund type; standard Solana fee holds use solana_fee_hold.

{
  "success": true,
  "refunds": [
    {
      "id": "refund_solana_example",
      "tradeId": "canonical_solana_refund_example",
      "blockchain": "solana",
      "giveNft": { "id": "J4Ev2zBa7np5wJH2FZ7Jg3m5JgyrB6sJmaXbMkLLk8hW", "name": "Synthetic Give Card", "image": "https://cdn.example/refund-give.png", "collection": "Synthetic Collection" },
      "wantNft": { "id": "CzLukYPdyyBoUxxJXSS1Ccg4pSZ7mHLdpxoYSUmfWmm7", "name": "Synthetic Wanted Card", "image": "https://cdn.example/refund-want.png", "collection": "Synthetic Collection" },
      "refundLamports": "149289383",
      "refundSol": 0.149289383,
      "refundStatus": "available",
      "refundType": "pnft_shared_escrow",
      "availableAt": "2026-05-31T20:00:00.000Z"
    }
  ],
  "total": 1
}

Ethereum and Base use the EVM branch. refundWei is the exact base-unit amount and refundEth is its ETH display value. The inherited refundLamports and refundSol compatibility fields are always zero for these rows; do not use them for EVM refund calculations. This synthetic example uses Base.

{
  "success": true,
  "refunds": [
    {
      "id": "refund_base_example",
      "tradeId": "canonical_base_refund_example",
      "blockchain": "base",
      "giveNft": { "id": "0x1111111111111111111111111111111111111111:17", "name": "Synthetic Give Card", "image": "https://cdn.example/refund-give.png", "collection": "Synthetic Collection" },
      "wantNft": { "id": "0x2222222222222222222222222222222222222222:42", "name": "Synthetic Wanted Card", "image": "https://cdn.example/refund-want.png", "collection": "Synthetic Collection" },
      "refundLamports": "0",
      "refundSol": 0,
      "refundWei": "5000000000000000",
      "refundEth": 0.005,
      "refundStatus": "available",
      "refundType": "evm_fee_escrow",
      "availableAt": "2026-05-31T20:00:00.000Z"
    }
  ],
  "total": 1
}

POST /api/v2/delegations/{nftId}/refund

Solana returns a serialized unsigned transaction. The response may omit the optional fee-hold addresses when they are not relevant to the selected refund.

{
  "success": true,
  "status": "awaiting_signature",
  "blockchain": "solana",
  "refund": {
    "tradeId": "canonical_solana_refund_example",
    "wantNftId": "CzLukYPdyyBoUxxJXSS1Ccg4pSZ7mHLdpxoYSUmfWmm7",
    "refundLamports": "149289383",
    "refundType": "pnft_shared_escrow"
  },
  "transaction": {
    "serialized": "AQAAAAAAAA...",
    "message": "Refund unused SWAPS completion fee",
    "estimatedFee": 5000,
    "refundFeeHoldAddress": "3y3f4Hia3hhwEt3ZwW2wu2xYzG69bAHwUYSjz7K89gcs",
    "feeReceiptAddress": "3aZnctdQhXwaW1RMULf8sHYu1vh1UZUExiRztWSNMZ8x"
  },
  "message": "Sign this transaction to reclaim the unused SWAPS completion fee for a non-winning approved trade. Solana network fees are not refundable."
}

Ethereum and Base return one EVM escrow-refund call. Base uses the same EVM shape. chainId is supplied when registry lookup succeeds and can be omitted if registry lookup is unavailable, so clients should validate or switch the wallet network whenever it is present.

{
  "success": true,
  "status": "awaiting_signature",
  "blockchain": "base",
  "chainId": 8453,
  "refund": {
    "tradeId": "canonical_base_refund_example",
    "wantNftId": "0x2222222222222222222222222222222222222222:42",
    "refundWei": "5000000000000000",
    "refundEth": 0.005,
    "refundType": "evm_fee_escrow"
  },
  "transaction": {
    "to": "0x4444444444444444444444444444444444444444",
    "data": "0x1234abcd",
    "value": "0",
    "gasLimit": "60000",
    "maxFeePerGas": "1000000000",
    "maxPriorityFeePerGas": "100000000",
    "message": "Refund unused SWAPS completion fee",
    "estimatedFee": 60000
  },
  "message": "Sign this transaction to reclaim the escrowed SWAPS completion fee for a trade that can no longer execute. Gas fees are not refundable."
}

Network fees are not refundable. Solana transaction.estimatedFee is lamports; the EVM transaction.estimatedFee mirrors the estimated gas-unit limit and is not an ETH fee quote.

Partner Readiness

GET /api/v2/partners/readiness

{
  "success": true,
  "ready": true,
  "tradeHealth": {
    "totalWallets": 250,
    "totalNfts": 1400,
    "totalOpportunities": 42,
    "potentialSwaps": 42,
    "density": "moderate"
  },
  "recommendations": []
}

Webhook

{
  "event": "trade_loop_discovered",
  "timestamp": "2026-05-05T10:35:00.000Z",
  "tenant": {
    "id": "tenant_123",
    "name": "Example Collectibles"
  },
  "data": {
    "loop": {
      "id": "trade_123",
      "status": "discovered",
      "totalParticipants": 2,
      "estimatedValue": 42,
      "createdAt": "2026-05-05T10:35:00.000Z",
      "blockchain": "ethereum",
      "steps": [
        {
          "from": "0x1111111111111111111111111111111111111111",
          "to": "0x2222222222222222222222222222222222222222",
          "nfts": [
            {
              "address": "0x3333333333333333333333333333333333333333:1",
              "name": "Charizard PSA 10",
              "image": "https://cdn.example/charizard.png",
              "collection": "Pokemon Base Set",
              "floorPrice": 500,
              "currency": "USD"
            }
          ]
        }
      ]
    },
    "trigger": "want_submitted",
    "metadata": {
      "source": "api"
    }
  },
  "signature": "hmac_hex"
}