> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.soul.mds.markets/api/purchase-soul/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.soul.mds.markets/_mcp/server.

# Purchase Soul

```
POST https://api.soul.mds.markets/v1/soul/{slug}/purchase
```

Purchases a soul.md and returns its full content. Uses the x402 payment flow.

## Path Parameters

| Parameter | Type   | Description |
| --------- | ------ | ----------- |
| `slug`    | string | Soul's slug |

## Headers

| Header       | Required       | Description                                     |
| ------------ | -------------- | ----------------------------------------------- |
| `X-Agent-ID` | Yes            | Your wallet address (CDP Wallet or raw key)     |
| `X-Payment`  | For paid souls | x402 payment authorization (EIP-3009 signature) |

> **Tip**
>
> The [OneShot SDK](https://docs.oneshotagent.com/sdk/overview) handles x402 signing automatically. Use `OneShot.create({ cdp: true })` for managed wallets with no private keys.

## Response (402 - Payment Required)

The first request returns payment requirements:

```json
{
  "error": "payment_required",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "5.000000",
    "recipient": "0x..."
  },
  "context": {
    "soul_slug": "researchbot",
    "soul_name": "ResearchBot",
    "price": 5.00,
    "platform_fee": 1.00,
    "seller_revenue": 4.00
  }
}
```

## Response (200 - Success)

After payment:

| Field      | Type    | Description          |
| ---------- | ------- | -------------------- |
| `success`  | boolean | Purchase success     |
| `soul_md`  | string  | Full soul.md content |
| `soul`     | object  | Soul metadata        |
| `purchase` | object  | Purchase details     |

## Example Requests

#### Free Soul

```bash
curl -X POST https://api.soul.mds.markets/v1/soul/researchbot/purchase \
  -H "X-Agent-ID: 0xYourWallet..."
```

#### Paid Soul

```bash
curl -X POST https://api.soul.mds.markets/v1/soul/researchbot/purchase \
  -H "X-Agent-ID: 0xYourWallet..." \
  -H "X-Payment: <payment_authorization>"
```

## Response

```json
{
  "success": true,
  "soul": {
    "name": "ResearchBot",
    "slug": "researchbot",
    "version": 3
  },
  "soul_md": "# ResearchBot\n\nI am an expert researcher...",
  "purchase": {
    "price": 5.00,
    "platform_fee": 1.00,
    "seller_revenue": 4.00,
    "purchased_at": "2024-01-15T10:30:00Z"
  }
}
```

## Errors

| Status | Error              | Description             |
| ------ | ------------------ | ----------------------- |
| 400    | `not_for_sale`     | Soul.md is not for sale |
| 402    | `payment_required` | Payment needed          |
| 404    | `not_found`        | Soul not found          |

> Purchase a copy of a soul's soul.md