List recent pulls

Returns the most recent pulls across one or more packs, newest first.

GET /api/v1/vm/recent-pulls

List recent pulls

cURL

curl --request GET \
  --url https://api.example.com/api/v1/vm/recent-pulls

200

[
  {
    "id": "v1|110586049456|0",
    "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
    "claw_slug": "topps-chrome-2024",
    "value": 250.0,
    "buyback_price": 212.5,
    "created_at": "2026-04-30T17:42:11.123Z",
    "metadata": {
      "name": "2024 Topps Chrome Juan Soto RC Auto /25",
      "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
      "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png",
      "attributes": [
        { "trait_type": "Sport", "value": "Baseball" },
        { "trait_type": "Year", "value": "2024" }
      ]
    }
  },
  {
    "id": "v1|110586049457|0",
    "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
    "claw_slug": "topps-chrome-2024",
    "value": 82.5,
    "buyback_price": 70.13,
    "created_at": "2026-04-30T17:42:11.123Z",
    "metadata": {
      "name": "2024 Topps Chrome Common Card",
      "image": "https://cdn.phygitals.com/cards/common.png",
      "back_image": null,
      "attributes": []
    }
  }
]

Returns the most recent pulls across one or more packs, ordered newest first. Use this to drive a live “recent pulls” feed on a pack detail page or a pack-list dashboard.

Query parameters

claw_ids · string[]

Pack identifiers (each is the id returned by /api/v1/vm/available). Repeat the parameter to filter by multiple packs:

GET /api/v1/vm/recent-pulls?claw_ids=BSG6Dy...&claw_ids=GFkLm...

Omit to return recent pulls across all packs.

limit · integer · default: "20"

Maximum number of pulls to return. Clamped to the range [1, 100]; non-numeric values fall back to the default of 20.

Example request

GET /api/v1/vm/recent-pulls?claw_ids=BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM&limit=10
X-API-Key: <your_api_key>

Response

200

[
  {
    "id": "v1|110586049456|0",
    "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
    "claw_slug": "topps-chrome-2024",
    "value": 250.0,
    "buyback_price": 212.5,
    "created_at": "2026-04-30T17:42:11.123Z",
    "metadata": {
      "name": "2024 Topps Chrome Juan Soto RC Auto /25",
      "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
      "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png",
      "attributes": [
        { "trait_type": "Sport", "value": "Baseball" },
        { "trait_type": "Year", "value": "2024" }
      ]
    }
  },
  {
    "id": "v1|110586049457|0",
    "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
    "claw_slug": "topps-chrome-2024",
    "value": 82.5,
    "buyback_price": 70.13,
    "created_at": "2026-04-30T17:42:11.123Z",
    "metadata": {
      "name": "2024 Topps Chrome Common Card",
      "image": "https://cdn.phygitals.com/cards/common.png",
      "back_image": null,
      "attributes": []
    }
  }
]

Fields

id · string

Item identifier. Equal to mint_address for items already minted on-chain, otherwise the source listing id (e.g. eBay listing id).

claw_id · string

The pack the item was pulled from. Matches the id returned by /api/v1/vm/available and the claw_id accepted by /api/v1/vm/buyback.

claw_slug · string | null

URL-friendly slug of the pack. Same value as the slug returned by /api/v1/vm/available. null for packs without a slug configured.

value · number

Fair-market value of the pulled item in USD.

For real production pulls this is the live FMV recorded on the source listing (eBay listing’s fmv or the on-chain item’s altFmv). For sandbox-only synthetic pulls this is approximated as buyback_price / 0.85 because the sandbox does not store the original FMV.

buyback_price · number

Sellback price in USD: value * pack.buyback_percent. Use as the canonical “what we’d pay back” amount.

created_at · string

ISO 8601 timestamp the pull was recorded.

metadata · object

Standard NFT metadata for the pulled item.

• name — Item name.
• image — CDN URL for the item image.
• back_image — CDN URL for the card back image, or null when not available.
• attributes — Array of { trait_type, value } entries.

Errors

Status	Body	Meaning
500	{ "error": "An unexpected error occurred" }	Internal error while building the recent-pull list.

Unknown claw_ids, an empty result set, and unparseable limit values do not error: the response is 200 [] (or 200 with whatever subset of pulls match) and limit falls back to the default of 20.