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

# Buy with crypto

> Submit a signed crypto payment to open claw packs and receive digital items.

Submits a crypto payment for one or more claw pulls. You build and sign the on-chain payment transaction client-side, then send it to Phygitals for co-signing, bundling, and fulfillment.

<Note>
  **Scope required:** `vm.buy.crypto`. See [authentication](/public-api/authentication) for how to send your key.
</Note>

<Warning>
  This endpoint is rate-limited to **1 request per 60 seconds** per API key.
</Warning>

## Prerequisites

1. A user API key with the `vm.buy.crypto` scope
2. A linked external Solana wallet with sufficient USDC or USDT
3. Pack details from [`GET /api/vm/available`](/public-api/packs/list) — note the pack `id` and `mint_price`
4. Signer public keys from `POST /api/orpc/config/signers/pubkeys` (no authentication required) to construct valid transactions

## Request body

<ParamField body="claw_id" type="string" required>
  Pack ID (mint address) from `/api/vm/available`.
</ParamField>

<ParamField body="amount" type="integer" required>
  Number of pulls. Must be a positive integer.
</ParamField>

<ParamField body="currency" type="string" required>
  Payment token. Supported values depend on `chain` — for Solana: `usdc`, `usdt`.
</ParamField>

<ParamField body="chain" type="string" required>
  Payment chain. For example `solana` or an EVM chain slug supported by the pack.
</ParamField>

<ParamField body="txs" type="array" required>
  Array of serialized, **signed** payment transactions. Each entry is a byte array (JSON) or base64 string. On Solana, the buyer wallet must be a signer on the payment transaction.
</ParamField>

<ParamField body="voucher_id" type="string">
  Optional voucher ID or code. When provided, the payment transfer may be skipped if the voucher covers the purchase.
</ParamField>

<ParamField body="permit_data" type="object">
  Required for paid EVM purchases. ERC-20 permit signature authorizing the payment token transfer.
</ParamField>

<ParamField body="buyer_wallet" type="string">
  **API key requests only.** Solana or EVM address that pays for and receives the items. When omitted, your account's primary linked wallet is used. The wallet must sign the payment transaction. Vouchers attached to your account remain yours to spend regardless of which `buyer_wallet` you specify.
</ParamField>

<ParamField body="extraData" type="object">
  Optional metadata attached to the purchase session.
</ParamField>

## Example request

```http theme={"dark"}
POST /api/vm/buy/crypto
X-API-Key: phy_your_secret_key
Content-Type: application/json

{
  "claw_id": "BSG6DyEihFFtfvxtL9mKYsvTwiZXB1rq5gARMTJC2xAM",
  "amount": 1,
  "currency": "usdc",
  "chain": "solana",
  "txs": [[/* signed VersionedTransaction bytes */]]
}
```

## Response

On success the API returns the fulfilled purchase. If fulfillment is still in progress, the response includes a `session_id` — poll [`POST /api/vm/buy/status`](/public-api/purchase/status) until items are ready.

<ResponseExample>
  ```json 200 theme={"dark"}
  {
    "result": {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "did:privy:abc123",
      "public_id": "_a1b2c3d4",
      "total": 25.00,
      "tx_hash": "5Kn8...bundle_signature",
      "nfts": [
        {
          "id": "9XnY...mint_address",
          "type": "enft",
          "buyback_price": 21.25,
          "content": {
            "metadata": {
              "name": "2024 Juan Soto RC Auto /25",
              "image": "https://cdn.phygitals.com/cards/example.png"
            }
          }
        }
      ]
    }
  }
  ```
</ResponseExample>

<ResponseField name="result.session_id" type="string">
  Purchase session ID. Pass to `/api/vm/buy/status` if `nfts` is empty or fulfillment is pending.
</ResponseField>

<ResponseField name="result.nfts" type="array">
  Pulled items. Each entry includes an `id` (mint address), metadata, and `buyback_price` when applicable.
</ResponseField>

<ResponseField name="result.tx_hash" type="string">
  On-chain transaction or bundle signature for the purchase.
</ResponseField>

## Error responses

| Status | Example                                            | Cause                                                              |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------ |
| `400`  | `{ "error": "amount must be a positive integer" }` | Invalid `amount`                                                   |
| `400`  | `{ "error": "Unsupported currency: …" }`           | Unknown `currency` / `chain` pair                                  |
| `400`  | `{ "error": "…" }`                                 | Pack out of stock, invalid transaction, or business-rule rejection |
| `401`  | `{ "message": "Invalid or missing credentials" }`  | Missing or invalid API key                                         |
| `429`  | `{ "message": "Rate limit exceeded" }`             | More than one request per 60 seconds                               |
| `500`  | `{ "error": "Error during transaction" }`          | Unexpected server error                                            |

## Integration flow

```mermaid theme={"dark"}
sequenceDiagram
    autonumber
    participant C as Your script
    participant A as Phygitals API
    participant S as Solana

    C->>A: GET /api/vm/available
    A-->>C: pack list
    C->>A: POST /api/orpc/config/signers/pubkeys
    A-->>C: fee payer + buyback pubkeys
    C->>S: Build & sign payment tx
    C->>A: POST /api/vm/buy/crypto
    alt Immediate fulfillment
        A-->>C: { result: { nfts: [...] } }
    else Pending
        A-->>C: { result: { session_id } }
        loop Poll
            C->>A: POST /api/vm/buy/status
            A-->>C: { result: { nfts } } or pending
        end
    end
```

<Note>
  Transaction construction is chain-specific. Refer to the Phygitals web client or contact [hello@phygitals.com](mailto:hello@phygitals.com) for integration support on your target chain.
</Note>