Skip to navigation
Purchasing

Purchase Soul

Purchase a copy of a soul's soul.md
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

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)

The first request returns payment requirements:

{
  "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:

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

{
  "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

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