Skip to main content
POST
/
api
/
vm
/
buy
/
status
Poll purchase status
curl --request POST \
  --url https://api.example.com/api/vm/buy/status \
  --header 'Content-Type: application/json' \
  --data '
{
  "session_id": "<string>"
}
'
{
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "did:privy:abc123",
    "public_id": "_a1b2c3d4",
    "tx_hash": "5Kn8...bundle_signature",
    "nfts": [
      {
        "id": "9XnY...mint_address",
        "type": "enft",
        "buyback_price": 21.25,
        "mint_address": "9XnY...mint_address",
        "content": {
          "metadata": {
            "name": "2024 Juan Soto RC Auto /25",
            "image": "https://cdn.phygitals.com/cards/example.png"
          },
          "links": {
            "image": "https://cdn.phygitals.com/cards/example.png"
          }
        }
      }
    ]
  }
}
Polls the status of a purchase session created by POST /api/vm/buy/crypto. The server holds the connection open and checks fulfillment internally before responding.
Scope required: vm.buy.crypto

​
Request body

​
session_id
string
required
Session ID from the buy/crypto response (result.session_id).

​
Example request

POST /api/vm/buy/status
X-API-Key: phy_your_secret_key
Content-Type: application/json

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

​
Response

{
  "result": {
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "did:privy:abc123",
    "public_id": "_a1b2c3d4",
    "tx_hash": "5Kn8...bundle_signature",
    "nfts": [
      {
        "id": "9XnY...mint_address",
        "type": "enft",
        "buyback_price": 21.25,
        "mint_address": "9XnY...mint_address",
        "content": {
          "metadata": {
            "name": "2024 Juan Soto RC Auto /25",
            "image": "https://cdn.phygitals.com/cards/example.png"
          },
          "links": {
            "image": "https://cdn.phygitals.com/cards/example.png"
          }
        }
      }
    ]
  }
}
​
result.nfts
array
Pulled items once fulfillment completes. Empty or absent while the purchase is still processing.
​
result.public_id
string
Public reveal identifier for the pull (shareable link prefix).
​
status
string
Present when fulfillment has not completed within the server poll window. Retry after a short delay.

​
Error responses

StatusExampleCause
400{ "error": "Transaction failed" }On-chain purchase failed
401{ "message": "Invalid or missing credentials" }Missing or invalid API key

​
Polling guidance

  • Call this endpoint after buy/crypto when the initial response has a session_id but no nfts
  • The server polls for up to ~6 seconds before returning a pending status
  • On the client side, retry with 500–1000 ms between attempts until result.nfts is populated or an error is returned
  • Stop polling on 400 with "Transaction failed"