Paid Endpoints

These endpoints require an x402 payment. Without payment, they return 402 Payment Required.

Hybrid Search — $0.01¶

GET /search/hybrid?q={query}

Combines BM25 keyword search with vector semantic search using Reciprocal Rank Fusion (RRF) for high-quality results.

Parameter	Type	Default	Description
`q`	string	required	Search query
`limit`	number	20	Max results (1-50)

How Hybrid Search Works¶

graph LR Q[Query: 'overcoming fear'] --> BM25[BM25 Keyword Search] Q --> VEC[Vector Semantic Search] BM25 --> RRF[Reciprocal Rank Fusion] VEC --> RRF RRF --> R[Ranked Results]

BM25 finds exact keyword matches (fast, precise)
Vector search finds semantically similar content (understands meaning)
RRF merges both ranked lists into a single high-quality result set

Example¶

# With x402 client (payment handled automatically)
fetchWith402('https://book402.com/search/hybrid?q=overcoming+fear&limit=5')

Response¶

{
  "data": [
    {
      "id": 2350,
      "title": "A Handbook for New Stoics",
      "author": "Gregory Lopez; Massimo Pigliucci",
      "genre": "Personal Development",
      "chunk": "The impediment to action advances action. What stands in the way becomes the way...",
      "score": 0.94
    },
    {
      "id": 1204,
      "title": "The Obstacle Is the Way",
      "author": "Ryan Holiday",
      "genre": "Philosophy",
      "chunk": "There is no good or bad without us, there is only perception...",
      "score": 0.89
    }
  ]
}

Summary Search — $0.01¶

GET /search/summaries?q={query}

Full-text search specifically within book summaries (not metadata). Great for finding books by concept or theme.

Parameter	Type	Default	Description
`q`	string	required	Search query
`limit`	number	20	Max results

Get Book Summary — $0.05¶

GET /books/:id/summary

Returns the complete AI-generated summary for a specific book.

Example¶

fetchWith402('https://book402.com/books/1847/summary')

Response¶

{
  "id": 1847,
  "title": "Atomic Habits",
  "author": "James Clear",
  "summary": "James Clear's Atomic Habits presents a comprehensive framework for building good habits and breaking bad ones, centered around the idea that small, incremental changes compound into remarkable results over time..."
}

Payment Flow for All Paid Endpoints¶

stateDiagram-v2 [*] --> Request: Agent sends GET request Request --> PaymentRequired: No payment header PaymentRequired --> SignPayment: Agent reads PAYMENT-REQUIRED header SignPayment --> RetryWithPayment: Agent signs EIP-3009 authorization RetryWithPayment --> Verify: Server receives X-PAYMENT header Verify --> Deliver: Facilitator confirms signature ✅ Verify --> Reject: Invalid signature ❌ Deliver --> Settle: Server returns 200 + data Settle --> [*]: Facilitator settles USDC on-chain Reject --> [*]: Server returns 403