Vault API

Three endpoints for searching, purchasing, and downloading digital assets. All gated by x402 micropayments.

Search

Search for skills, knowledge bases, and personas.

Cost: $0.01 USDC

GET /x402/vault/search

Parameter	Type	Required	Description
q	string	No	Search query
category	string	No	marketing, development, automation, career, ios, productivity
productType	string	No	skill, knowledge, persona
minPrice	integer	No	Minimum price in USDC
maxPrice	integer	No	Maximum price in USDC
cursor	string	No	Pagination cursor (UUID)
limit	integer	No	Items per page (1-100, default 30)

Response

{
  "items": [
    {
      "id": "550e8400-...",
      "slug": "marketing-automation-pro",
      "title": "Marketing Automation Pro",
      "productType": "skill",
      "cardDescription": "Automate your entire marketing workflow...",
      "price": 5,
      "category": "marketing",
      "creator": { "name": "Purch", "type": "human" },
      "downloads": 42,
      "coverImageUrl": "https://..."
    }
  ],
  "nextCursor": null
}

Buy

Purchase a vault item. The x402 payment amount equals the item's price in USDC — paid automatically by your x402 client.

Cost: Item price (dynamic)

POST /x402/vault/buy

Field	Type	Required	Description
slug	string	Yes	Vault item slug
walletAddress	string	Yes	Solana wallet address (base58)
email	string	Yes	Email for purchase confirmation

Response

{
  "purchaseId": "15d05c3c-...",
  "downloadToken": "bfd489b8a763168f...",
  "item": {
    "slug": "marketing-automation-pro",
    "title": "Marketing Automation Pro",
    "productType": "skill",
    "price": 5,
    "coverImageUrl": "https://..."
  }
}

Download

Download the purchased file. Returns a ZIP archive.

Cost: $0.01 USDC

GET /x402/vault/download/:purchaseId

Parameter	Type	Required	Description
downloadToken	string	Yes	Secret token from buy response

Example

const file = await fetchWithPay(
  `https://api.purch.xyz/x402/vault/download/${purchaseId}?downloadToken=${downloadToken}`
);
const zip = await file.arrayBuffer();

Since payment was handled via x402 during purchase, no transaction signature is needed for download.

Full Agent Flow

// 1. Search
const search = await fetchWithPay(
  "https://api.purch.xyz/x402/vault/search?limit=3"
);
const { items } = await search.json();

// 2. Buy (x402 handles payment automatically)
const buy = await fetchWithPay("https://api.purch.xyz/x402/vault/buy", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    slug: items[0].slug,
    walletAddress: "YOUR_WALLET",
    email: "agent@example.com",
  }),
});
const { purchaseId, downloadToken } = await buy.json();

// 3. Download
const file = await fetchWithPay(
  `https://api.purch.xyz/x402/vault/download/${purchaseId}?downloadToken=${downloadToken}`
);
const zip = await file.arrayBuffer();