Credits Endpoints

Manage your credit balance for API operations and storage insurance.

Deposit Credits

Deposit credits into your account via x402 payment. This enables autonomous agents to fund their own storage insurance without human intervention.

Endpoint: POST /credits/deposit

Query Parameters

x402 Payment Flow

This endpoint uses the x402 protocol for permissionless payments:

1. Initial Request: Call the endpoint without payment
2. 402 Response: Receive payment requirements (supported networks, amounts, recipient)
3. Sign Payment: Use your wallet to sign an x402 payment
4. Retry with Payment: Retry the request with x-payment header containing the signed payment
5. Success: Receive confirmation and updated balance

Example: Initial Request

curl -X POST "https://api.zkstash.ai/v1/credits/deposit?amount_usd=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: 402 Response

{
  "x402Version": 1,
  "error": "Payment required for credit deposit",
  "deposit": {
    "amount_usd": 5,
    "credits": 5000,
    "description": "Credits will be added to your balance for future operations and storage insurance."
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "5000000",
      "resource": "https://api.zkstash.ai/v1/credits/deposit",
      "description": "Deposit 5,000 credits ($5.00 USD)",
      "mimeType": "application/json",
      "payTo": "...",
      "extra": { "feePayer": "..." }
    },
    {
      "scheme": "exact", 
      "network": "base",
      "maxAmountRequired": "5000000",
      "resource": "https://api.zkstash.ai/v1/credits/deposit",
      "description": "Deposit 5,000 credits ($5.00 USD)",
      "mimeType": "application/json",
      "payTo": "..."
    }
  ]
}

Example: Success Response

After providing a valid x-payment header:

{
  "success": true,
  "deposit": {
    "amount_usd": 5,
    "credits": 5000
  },
  "balance": {
    "credits": 5000,
    "usd": 5
  },
  "message": "Deposit successful. Storage insurance is now active."
}

Use Cases

Storage Insurance for Free Plan

Free plan memories are deleted after 7 days by default. To prevent deletion:

1. Deposit credits using this endpoint
2. The daily cron job will deduct ~3.33 credits per 1,000 memories to “insure” your storage
3. As long as you maintain a positive balance, your memories persist

Autonomous Agent Self-Funding

Agents that earn revenue (e.g., by providing services) can use those funds to:

1. Pay for their own storage costs
2. Pre-fund future API operations
3. Operate indefinitely without human intervention

This enables self-sovereign AI agents—a capability unique to crypto-native platforms.

Supported Networks