Skip to main content
POST
/
api
/
v1
/
vm
/
buy
/
status
Poll purchase status
curl --request POST \
  --url https://api.example.com/api/v1/vm/buy/status \
  --header 'Content-Type: application/json' \
  --data '
{
  "session_id": "<string>"
}
'
{
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "user_abc123",
    "public_id": "_XKCD",
    "nfts": [
      {
        "id": "9XnY...mint_address",
        "buyback_price": 8.50,
        "mint_address": "9XnY...mint_address",
        "content": {
          "metadata": {
            "name": "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"
          },
          "links": {
            "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
            "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png"
          }
        }
      }
    ],
    "tx_hash": "transaction_hash"
  }
}
Polls a purchase session created by /api/v1/vm/buy/init. Call this after buy/init until the status is fulfilled.

​
Request body

​
session_id
string
required
The session_id returned by /api/v1/vm/buy/init.

​
Example request

POST /api/v1/vm/buy/status
X-API-Key: <your_api_key>
Content-Type: application/json

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Response: fulfilled

{
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "user_abc123",
    "public_id": "_XKCD",
    "nfts": [
      {
        "id": "9XnY...mint_address",
        "buyback_price": 8.50,
        "mint_address": "9XnY...mint_address",
        "content": {
          "metadata": {
            "name": "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"
          },
          "links": {
            "image": "https://cdn.phygitals.com/cards/soto-rc-auto.png",
            "back_image": "https://cdn.phygitals.com/cards/soto-rc-auto-back.png"
          }
        }
      }
    ],
    "tx_hash": "transaction_hash"
  }
}
​
result.session_id
string
Echoes back the session_id from /api/v1/vm/buy/init.
​
result.user_id
string
Echoes back the user_id from /api/v1/vm/buy/init.
​
result.public_id
string
Short shareable transaction identifier (for example _XKCD).
​
result.nfts[].id
string
Item identifier. Used as item_id in /api/v1/vm/buyback. Equal to mint_address for on-chain items.
​
result.nfts[].mint_address
string | null
On-chain mint address for the item. null for items that haven’t been minted on-chain (in sandbox, always null for ebay-sourced items).
​
result.nfts[].buyback_price
number
Sellback value in USD.
​
result.nfts[].type
string
Item source. One of: enft, ebay, fanatics, alt, external.
​
result.nfts[].collection_address
string | null
On-chain collection address.
​
result.nfts[].token_standard
string | null
Token standard for on-chain items.
​
result.nfts[].content.metadata
object
Item metadata (name, image, back_image, attributes). Use metadata.image as the canonical image URL.
​
result.nfts[].content.metadata.back_image
string | null
CDN URL for the card back image, or null when not available.
​
result.nfts[].content.links.image
string
Direct CDN URL for the item image. In sandbox, this is not populated on buy/status responses (it only appears on inventory items). Treat it as a fallback when present.
​
result.nfts[].content.links.back_image
string | null
CDN URL for the card back image. Mirror of content.metadata.back_image.
​
result.tx_hash
string
On-chain transaction hash for the mint. In sandbox, tx_hash is a synthetic identifier of the form sandbox_<base64url> and does not correspond to any on-chain transaction.
See the item shape reference for the full canonical item schema.

​
Response: pending

{
  "status": "pending"
}
Returned if the server’s internal poll window expires before the order is fulfilled. Wait a few seconds and call again.
Sandbox: the { "status": "pending" } response is never returned. Sandbox fulfills synchronously inside buy/init, so the first buy/status call after a successful buy/init always returns the fulfilled { result: ... } envelope. Any unknown session_id returns 400 { "error": "Transaction failed" } immediately.

​
Response: failed

{
  "error": "Transaction failed"
}
Returned with status 400 when the transaction could not be completed. The purchase should be considered cancelled.