The Phygitals Partner API covers the endpoints needed to list available packs, display pack details, purchase items, sell items back, and ship physical items.
Blockchain naming in responses is a misnomer. Fields such as mint_address, tx_hash, nfts, and platform values like mainnet use blockchain terminology for historical reasons. Partner integrations do not move assets on-chain or submit blockchain transactions.
Base URLs
| Environment | Base URL |
|---|
| Production | https://api.phygitals.com |
| Sandbox | https://api.phygitals.com/_ (read-only, no real money or items move) |
/api/v1/. The sandbox mirrors the same routes under /_/api/v1/. For example, the full production URL for listing packs is https://api.phygitals.com/api/v1/vm/available and the sandbox equivalent is https://api.phygitals.com/_/api/v1/vm/available.
See the sandbox page for the full list of sandbox-only behaviors and how it differs from production.
Authentication
All requests require an API key provided by the Phygitals team. Include it in every request as a header:
X-API-Key: <your_api_key>
- Production keys identify your partner account and authorize live purchases, sellbacks, and shipments. Contact hello@phygitals.com.
- Sandbox keys (prefix
sandbox-) authorize the read-only sandbox at /_/api/v1/*. They do not identify a partner and never produce real money movement, on-chain transactions, or shipments. Use them to integrate without consuming inventory.
A 401 { "error": "Invalid API key" } is returned for missing, empty, or unrecognized X-API-Key headers on any endpoint, in either environment.
Treat your API key like a password. Never commit it to source control or expose it in client-side code. Store it in a secrets manager or environment variable, and only call Phygitals endpoints from your server.
Integration flow
Endpoint summary
| Method | Path | Description |
|---|
GET | /api/v1/vm/available | List all available packs |
GET | /api/v1/vm/chase/:slug | Top hits for a pack |
GET | /api/v1/vm/recent-pulls | Most recent pulls across packs |
POST | /api/v1/vm/buy/init | Purchase items from a pack |
POST | /api/v1/vm/buy/status | Poll purchase fulfillment |
GET | /api/v1/inventory/:user_id | List items owned by a user |
GET | /api/v1/card/:item_id | Get full details for a single card |
POST | /api/v1/vm/buyback | Sell an item back to the pack |
POST | /api/v1/ship/quote | Get shipping rate quotes |
POST | /api/v1/ship/request | Submit a shipping request |
GET | /api/v1/ship/order/:order_id | Get shipping order details |
User identifiers
Every purchase is tagged with a partner-defined user_id. Items pulled for a given user_id are owned by that user until they’re sold back or shipped. Use your own internal user IDs. Phygitals does not assign them.
The same user_id flows through inventory lookup, sellback, shipping quotes, and shipping requests, so you can scope all activity to the end user on your platform. 
