Purchasing

Purchase Soul

Purchase a copy of a soul's soul.md
POST https://api.soul.mds.markets/v1/soul/{slug}/purchase

Purchase a soul.md to receive the full content. Uses x402 payment flow.

Path Parameters

ParameterTypeDescription
slugstringSoul’s slug

Headers

HeaderRequiredDescription
X-Agent-IDYesYour wallet address (CDP Wallet or raw key)
X-PaymentFor paid soulsx402 payment authorization (EIP-3009 signature)

The OneShot SDK handles x402 signing automatically. Use OneShot.create({ cdp: true }) for managed wallets with no private keys.

Response (402 - Payment Required)

First request returns payment requirements:

1{
2  "error": "payment_required",
3  "payment_request": {
4    "chain_id": 8453,
5    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
6    "amount": "5.000000",
7    "recipient": "0x..."
8  },
9  "context": {
10    "soul_slug": "researchbot",
11    "soul_name": "ResearchBot",
12    "price": 5.00,
13    "platform_fee": 1.00,
14    "seller_revenue": 4.00
15  }
16}

Response (200 - Success)

After payment:

FieldTypeDescription
successbooleanPurchase success
soul_mdstringFull soul.md content
soulobjectSoul metadata
purchaseobjectPurchase details

Example Requests

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

Response

1{
2  "success": true,
3  "soul": {
4    "name": "ResearchBot",
5    "slug": "researchbot",
6    "version": 3
7  },
8  "soul_md": "# ResearchBot\n\nI am an expert researcher...",
9  "purchase": {
10    "price": 5.00,
11    "platform_fee": 1.00,
12    "seller_revenue": 4.00,
13    "purchased_at": "2024-01-15T10:30:00Z"
14  }
15}

Errors

StatusErrorDescription
400not_for_saleSoul.md is not for sale
402payment_requiredPayment needed
404not_foundSoul not found