Zing

Pay-Per-Query API

The Pay-Per-Query (PPQ) system enables AI agents and researchers to pay micro-fees for accessing specific content chunks from the search index. This creates a new revenue stream for creators — earning royalties not just from readers, but from machine intelligence.

What is Pay-Per-Query?

Pay-Per-Query is a micro-transaction model where users pay a token-based fee for each chunk of content retrieved by an AI:

  • Traditional Content: Pay $X/month for all content
  • Pay-Per-Query: Pay per chunk based on token count ($0.0004/1K tokens + creator rate)

This is particularly valuable for:

  • AI Agents - Pay only for data they actually use
  • Researchers - Access specific content without full memberships
  • Developers - Build applications on creator content

How It Works

Content is chunked at indexing time (~200 tokens per chunk). Each query retrieves chunks ranked by relevance, and you pay only for what you retrieve:

User Query → Vector + Lexical Search → RRF Merge → Cross-encoder Rerank
    │
    ▼
Top-K Chunks (ranked by blended score)
    │
    ▼
Budget-based greedy accumulation (highest score first)
    │
    ▼
Payment: flat_fee + Σ(token_based_chunk_fees)
    │
    ▼
Results returned with budget breakdown
POST/chunks

Retrieve Chunks (Paid)

Initiate and execute a chunk retrieval. The request includes a signed ApiAccessMessage and an on-chain USDC payment. Results are returned greedily within budget.

Required attributes

  • Name
    q
    Type
    string
    Description

    Search query.

  • Name
    wiki
    Type
    string
    Description

    global or owner address.

  • Name
    limit
    Type
    integer
    Description

    Max chunks to retrieve (capped at 50).

  • Name
    transaction_digest
    Type
    string
    Description

    Sui transaction digest for payment verification.

  • Name
    signature
    Type
    string
    Description

    Base64-encoded Sui wallet signature.

  • Name
    bytes
    Type
    string
    Description

    Base64-encoded BCS ApiAccessMessage.

Optional attributes

  • Name
    expand
    Type
    boolean
    Description

    When true, returns full chunk_text instead of excerpt (no extra charge).

  • Name
    article_ids
    Type
    array
    Description

    Filter to specific article IDs.

Request

POST
/chunks
curl -X POST https://search.zing.services/chunks \
  -H "Content-Type: application/json" \
  -d '{
    "q": "what is DeFi?",
    "wiki": "global",
    "limit": 10,
    "expand": false,
    "transaction_digest": "0xabc...",
    "signature": "sig...",
    "bytes": "bcs..."
  }'
POST/chunk/expand

Expand Chunks

Retrieve full untruncated text for up to 20 chunks. Requires a signed ExpandAccessMessage and USDC payment. Chunks returned greedily within budget.

Required attributes

  • Name
    chunk_ids
    Type
    array
    Description

    Chunk IDs to expand (max 20).

  • Name
    transaction_digest
    Type
    string
    Description

    Sui transaction digest.

  • Name
    signature
    Type
    string
    Description

    Base64-encoded signature.

  • Name
    bytes
    Type
    string
    Description

    Base64-encoded BCS ExpandAccessMessage.

Request

POST
/chunk/expand
curl -X POST https://search.zing.services/chunk/expand \
  -H "Content-Type: application/json" \
  -d '{
    "chunk_ids": [1603, 94, 1802],
    "transaction_digest": "5KzN...",
    "signature": "AM3x...",
    "bytes": "BQAAAGNo..."
  }'

Fee Structure

Cost Formula

flat_fee = $0.0005 (limit ≤ 20, scales linearly for larger limits)
base_fee = chunk_tokens / 1000 × $0.0004
content_fee = chunk_tokens / 1000 × creator_rate (0 if subscribed)
item_cost = base_fee + content_fee
total_consumed = flat_fee + sum(item_costs)

Revenue Split

PartyShare
Creator80% of content_fee + 0% of base_fee
Platformflat_fee + base_fee + 20% of content_fee

Creator Fee Levels

Creators set per-level content fees (levels 0–2). Default: 800 micro-USDC per 1K tokens ($0.0008). Range: 100–2000 ($0.0001–$0.002).

Budget Model

Chunks are returned greedily within budget — highest blended score first. Any unused payment stays on the platform as credit (remaining_usdc). Items below the 0.15 relevance threshold are excluded before budget calculation.

Example Calculation

Query: "latest DeFi trends"
Budget sent: $0.01 USDC

Flat fee: $0.0005
Chunk 1: 116 tokens × ($0.0004 + $0.0008)/1K = $0.000139 → blended_score: 2.14 ✓
Chunk 2: 88 tokens × ($0.0004 + $0.0012)/1K = $0.000141 → blended_score: 1.85 ✓
Chunk 3: 200 tokens × ($0.0004 + $0.0008)/1K = $0.000240 → blended_score: 1.62 ✓
...

Total consumed: $0.000797
Remaining: $0.009203

Payment Flow

Client
  │
  ▼
Sign ApiAccessMessage + send USDC to Platform
  │
  ▼
POST /chunks with signature + transaction_digest
  │
  ▼
Server verifies signature + on-chain payment
  │
  ▼
Runs search pipeline (vector + lexical + cross-encoder)
  │
  ▼
Calculates per-chunk cost based on token_count × rates
  │
  ▼
Greedily accumulates chunks within budget (highest score first)
  │
  ▼
Records payment + creator earnings in DB
  │
  ▼
Returns chunks + budget breakdown

Security Features

Cryptographic Binding: Each API call is cryptographically bound to a Sui transaction via signature verification. Without valid payment, chunks are not returned.

Attribution: All queries are recorded in the Attribution Ledger for creator transparency and royalty tracking.

Settlement: Creator earnings are settled via a background scheduler that batch-payouts accumulated balances every 5 minutes.

Next Steps

Was this page helpful?