> ## Documentation Index
> Fetch the complete documentation index at: https://dev.phygitals.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Base URL, authentication, and the end-to-end partner integration flow.

The Phygitals Partner API covers the endpoints needed to **list available packs**, **display pack details**, **purchase items**, **sell items back**, and **ship physical items**.

<Note>
  **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.
</Note>

## Base URLs

| Environment    | Base URL                                                               |
| -------------- | ---------------------------------------------------------------------- |
| **Production** | `https://api.phygitals.com`                                            |
| **Sandbox**    | `https://api.phygitals.com/_` (read-only, no real money or items move) |

All endpoints are versioned under `/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](/enterprise-api/sandbox) 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:

```http theme={"dark"}
X-API-Key: <your_api_key>
```

Two key tiers are issued:

* **Production keys** identify your partner account and authorize live purchases, sellbacks, and shipments. Contact [hello@phygitals.com](mailto: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.

<Warning>
  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.
</Warning>

## Integration flow

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    participant P as Partner App
    participant A as Phygitals API

    Note over P,A: Browse & display packs
    P->>A: GET /api/v1/vm/available
    A-->>P: pack list
    P->>A: GET /api/v1/vm/chase/:slug
    A-->>P: top hits

    Note over P,A: Purchase (async, two-step)
    P->>A: POST /api/v1/vm/buy/init
    A-->>P: { session_id }
    P->>A: POST /api/v1/vm/buy/status
    A-->>P: { result: { nfts: [...] } }

    Note over P,A: Inventory & sellback
    P->>A: GET /api/v1/inventory/:user_id
    A-->>P: { items: [...] }
    P->>A: POST /api/v1/vm/buyback
    A-->>P: { success: true }

    Note over P,A: Shipping
    P->>A: POST /api/v1/ship/quote
    A-->>P: { quotes: [...] }
    P->>A: POST /api/v1/ship/request
    A-->>P: { order_id, status }
    P->>A: GET /api/v1/ship/order/:order_id
    A-->>P: { status, tracking_number, ... }
```

## Endpoint summary

| Method | Path                           | Description                                                         |
| ------ | ------------------------------ | ------------------------------------------------------------------- |
| `GET`  | `/api/v1/vm/available`         | [List all available packs](/api-reference/packs/list)               |
| `GET`  | `/api/v1/vm/chase/:slug`       | [Top hits for a pack](/api-reference/packs/chase)                   |
| `GET`  | `/api/v1/vm/recent-pulls`      | [Most recent pulls across packs](/api-reference/packs/recent-pulls) |
| `POST` | `/api/v1/vm/buy/init`          | [Purchase items from a pack](/api-reference/purchase/init)          |
| `POST` | `/api/v1/vm/buy/status`        | [Poll purchase fulfillment](/api-reference/purchase/status)         |
| `GET`  | `/api/v1/inventory/:user_id`   | [List items owned by a user](/api-reference/inventory)              |
| `GET`  | `/api/v1/card/:item_id`        | [Get full details for a single card](/api-reference/cards/get)      |
| `POST` | `/api/v1/vm/buyback`           | [Sell an item back to the pack](/api-reference/sellback)            |
| `POST` | `/api/v1/ship/quote`           | [Get shipping rate quotes](/api-reference/shipping/quote)           |
| `POST` | `/api/v1/ship/request`         | [Submit a shipping request](/api-reference/shipping/request)        |
| `GET`  | `/api/v1/ship/order/:order_id` | [Get shipping order details](/api-reference/shipping/order)         |

## 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.