> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zkterm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# x402

> Internal payment system for zkStorage and zkAI services

## Overview

x402 is zkTerm's internal payment system that handles crypto payments for resource-consuming features like zkStorage (IPFS costs) and zkAI assistant (AI token usage).

**Status:** In Development

**Note:** All pricing shown below are examples only and subject to change before launch.

## Supported Services

| Service       | What You Pay For              | Cost Driver        |
| ------------- | ----------------------------- | ------------------ |
| **zkStorage** | IPFS file storage and pinning | Pinata API costs   |
| **zkAI**      | AI assistant responses        | OpenAI token usage |

## Payment Methods

x402 accepts cryptocurrency payments:

| Token    | Network | Status    |
| -------- | ------- | --------- |
| **ZKTR** | Solana  | Primary   |
| **SOL**  | Solana  | Supported |
| **USDC** | Solana  | Supported |

ZKTR is zkTerm's native token used for platform payments and governance.

## How It Works

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│    User     │      │   zkTerm    │      │  External   │
│   Wallet    │      │   x402      │      │  Services   │
├─────────────┤      ├─────────────┤      ├─────────────┤
│ 1. Pay ZKTR │ ───> │ 2. Credit   │ ───> │ 3. Pinata   │
│    or SOL   │      │    account  │      │    OpenAI   │
│             │ <─── │ 4. Deduct   │ <─── │ 5. Response │
│             │      │    balance  │      │             │
└─────────────┘      └─────────────┘      └─────────────┘
```

## zkStorage Payments

When you upload files to zkStorage, x402 handles the payment:

1. File encrypted client-side
2. x402 checks your credit balance
3. Upload processed via Pinata
4. Credits deducted based on file size

**Pricing (example only, subject to change):**

| File Size      | Cost     |
| -------------- | -------- |
| Up to 10 MB    | Free     |
| 10 MB - 100 MB | 0.1 ZKTR |
| 100 MB - 1 GB  | 1 ZKTR   |
| 1 GB+          | 10 ZKTR  |

## zkAI Payments

AI assistant usage is metered by token consumption:

1. You send a message to zkAI
2. x402 checks your credit balance
3. Request sent to AI provider
4. Credits deducted based on tokens used

**Pricing (example only, subject to change):**

| Usage             | Cost      |
| ----------------- | --------- |
| Simple query      | 0.01 ZKTR |
| Code generation   | 0.05 ZKTR |
| Long conversation | 0.1 ZKTR  |

## Terminal Commands

### Check Balance

```bash theme={null}
zk credits balance
```

**Output:**

```
x402 CREDITS

  ZKTR Balance:  125.50 ZKTR
  SOL Balance:   2.5 SOL
  
  Estimated Usage:
  - ~1,255 zkStorage uploads (10MB)
  - ~12,550 zkAI queries
```

### Add Credits

```bash theme={null}
zk credits add <amount> --token ZKTR
```

**Example:**

```bash theme={null}
> zk credits add 100 --token ZKTR

ADDING CREDITS

  Amount:     100 ZKTR
  From:       Your connected wallet
  
  Confirm? (y/n): y
  
  Transaction:  5abc...def
  New Balance:  225.50 ZKTR
```

### View Usage History

```bash theme={null}
zk credits history
```

**Output:**

```
USAGE HISTORY

  Date        Service      Amount    Balance
  ─────────────────────────────────────────
  Dec 02      zkStorage    -0.1      225.40
  Dec 02      zkAI         -0.05     225.35
  Dec 01      zkStorage    -1.0      225.40
  Dec 01      Add Credits  +100      226.40
```

## API Reference

### Get Balance

```bash theme={null}
GET /api/x402/balance
```

**Response:**

```json theme={null}
{
  "zktr": "125.50",
  "sol": "2.5",
  "usdc": "0"
}
```

### Add Credits

```bash theme={null}
POST /api/x402/deposit
Content-Type: application/json

{
  "amount": "100",
  "token": "ZKTR",
  "txSignature": "5abc...def"
}
```

### Get Usage History

```bash theme={null}
GET /api/x402/history?limit=10
```

**Response:**

```json theme={null}
{
  "transactions": [
    {
      "date": "2024-12-02T10:30:00Z",
      "service": "zkStorage",
      "amount": "-0.1",
      "balance": "225.40",
      "details": "upload: document.pdf (15MB)"
    }
  ]
}
```

## Credit System

### How Credits Work

1. **Deposit** - Send ZKTR/SOL/USDC to your zkTerm account
2. **Internal Balance** - Credits tracked in zkTerm database
3. **Usage Deduction** - Automatic deduction when using paid services
4. **Withdraw** - Withdraw unused credits back to wallet

### Free Tier

New users get free credits to try zkTerm:

| Service   | Free Allowance |
| --------- | -------------- |
| zkStorage | 10 MB total    |
| zkAI      | 100 queries    |

### ZKTR Benefits

Paying with ZKTR provides:

1. **10% Discount** - Lower rates vs SOL/USDC
2. **Priority Processing** - Faster uploads and AI responses
3. **Governance Rights** - Vote on zkTerm features

## Security

1. **Non-Custodial** - You control your wallet, we only track credits
2. **Transparent Pricing** - All costs shown before confirmation
3. **Audit Trail** - Full transaction history available
4. **Refunds** - Unused credits can be withdrawn anytime

## Future Features

1. **Subscription Plans** - Monthly unlimited tiers
2. **Team Accounts** - Shared credit pools
3. **Staking Rewards** - Earn credits by staking ZKTR
4. **Referral Program** - Earn credits for inviting users