--- name: athenut-search description: Private web search API that accepts payments via Cashu ecash tokens (X-Cashu) or MPP Lightning invoices (WWW-Authenticate: Payment) metadata: type: http-api protocol: cashu-x-cashu, mpp-lightning unit: xsr --- # Athenut Search - Paid Web Search API Athenut is a private web search API. Each search costs 1 xsr (search result token). You pay by including a Cashu ecash token in the `X-Cashu` request header, or by paying a Lightning invoice via the [Machine Payments Protocol (MPP)](https://mpp.dev/protocol). The search API and Cashu mint are co-hosted at https://athenut.com All endpoints below (including `/search`, `/info`, `/search_count`, and Cashu mint `/v1/*`) are served from this URL. ## Web Interface (athenut.com) For simple Lightning payments via browser, use https://athenut.com: 1. Click "Top Up" 2. Select number of searches (43 sats per search) 3. Pay the Lightning invoice 4. xsr tokens are automatically minted and credited to your session The web UI uses the same underlying Cashu mint (xsr unit) as the API. ## Agent Safety Policy (Required) When acting as an AGENT with this skill: - Always ask for explicit user permission before spending tokens on a search, unless the user has already clearly instructed you to perform the search. - When receiving an HTTP 402 response, inspect the payment headers to understand the payment requirements before spending. - Never expose or log token values, wallet credentials, or payment preimages. ## HTTP 402 Payment Flow (NUT-24 / X-Cashu) This API uses the HTTP 402 Payment Required status with the `X-Cashu` header for payment negotiation. ### Flow 1. Send `GET /search?q=` without an `X-Cashu` header (or with an invalid/insufficient token). 2. The server responds with HTTP `402 Payment Required` and an `X-Cashu` response header containing a Cashu payment request (NUT-18 format). This request specifies the mint URL, unit (`xsr`), and amount (`1`). 3. Use a Cashu wallet to create a token worth exactly 1 xsr minted from `https://athenut.com`. 4. Retry the request with the `X-Cashu` header set to the token string (e.g. `cashuB...`). 5. On success, the server responds with HTTP `200` and the search results as JSON. ## MPP Lightning Payment Flow (Alternative) This API also supports the [Machine Payments Protocol (MPP)](https://mpp.dev/protocol) using Lightning Network BOLT11 invoices. ### Quick Commands 1. Get a 402 challenge with the Lightning invoice: ```bash curl -s -D- -o/dev/null -G --data-urlencode "q=" "https://athenut.com/search" ``` Look for `WWW-Authenticate: Payment ...` header with `request="..."` value. 2. Extract the BOLT11 invoice from the `request` parameter: ```bash python3 -c "import base64,json,sys; print(json.loads(base64.urlsafe_b64decode(sys.argv[1]+'=='))['methodDetails']['invoice'])" "" ``` 3. Pay the invoice with any Lightning wallet. Save the preimage (64-char hex). 4. Build the Authorization header (python one-liner): ```bash python3 -c "import base64,json,re,sys; h=sys.argv[1]; p=sys.argv[2]; e=lambda k: re.search(k+r'=\\\"([^\\\"]+)\\\"', h).group(1); c={'challenge':{k:e(k)for k in['id','realm','method','intent','request','expires']},'payload':{'preimage':p}}; print('Payment',base64.urlsafe_b64encode(json.dumps(c,separators=(',',':')).encode()).rstrip(b'=').decode())" '' '' ``` 5. Search with the credential: ```bash curl -s -H "Authorization: Payment " -G --data-urlencode "q=" "https://athenut.com/search" ``` ### Full Flow (Details) 1. Send `GET /search?q=` without any payment headers. 2. Server responds with HTTP `402 Payment Required` with: - `X-Cashu` header: Cashu payment request (NUT-18 format) - `WWW-Authenticate: Payment ...` header: MPP Lightning charge challenge 3. Extract `request="eyJhb..."` from the WWW-Authenticate header. 4. Base64url-decode the request to get invoice details: ```json { "amount": "43", "currency": "sat", "description": "Athenut web search", "methodDetails": { "invoice": "lnbc430n1p...", "paymentHash": "47c5effa...", "network": "mainnet" } } ``` 5. Pay `methodDetails.invoice` with a Lightning wallet. Save the preimage. 6. Build credential JSON: ```json { "challenge": { "id": "a1b2c3d4", "realm": "search.example.com", "method": "lightning", "intent": "charge", "request": "eyJhb...", "expires": "2026-03-20T12:05:00Z" }, "payload": { "preimage": "<64-char-hex>" } } ``` 7. Base64url-encode (compact, no padding) and retry with `Authorization: Payment `. Server verifies `sha256(preimage) == paymentHash` from the challenge. ## Getting xsr Tokens Athenut is a Cashu mint that supports the custom `xsr` unit. If you have sats, you can mint xsr tokens directly by paying a Lightning invoice to the mint. **Simple path (any wallet with Lightning):** 1. `POST https://athenut.com/v1/mint/quote/bolt11` with body `{"amount": 1, "unit": "xsr"}` 2. Pay the returned BOLT11 invoice with any Lightning wallet 3. `POST https://athenut.com/v1/mint/bolt11` with the quote ID and blinded messages to claim the tokens 4. Serialize as a Cashu token string (starts with `cashuB...`) Each token worth 1 xsr pays for one search. **Using a wallet with custom unit support:** Wallets like [CDK](https://github.com/cashu/cdk) support custom units and can mint and spend xsr directly without manual API calls. ## Endpoints ### `GET /search` Perform a web search. Requires payment via one of the supported methods. **Query parameters:** - `q` (required) - The search query string. **Request headers (one of):** - `X-Cashu` - A Cashu v4 token (starting with `cashuB...`) worth exactly 1 xsr, minted from `https://athenut.com`. - `Authorization: Payment ` - An MPP Lightning credential with a valid payment preimage (base64url-encoded JSON). **Success response (200):** ```json [ { "url": "https://example.com", "title": "Example Result", "description": "A description of the result", "age": "2025-01-01T00:00:00Z" } ] ``` **Payment required response (402):** Returned when no payment is provided, the token is invalid, or the token amount is not exactly 1 xsr. Response headers (used by clients that already understand the 402 payment flow): - `X-Cashu` header: NUT-18 payment request specifying the mint, unit, and amount needed. - `WWW-Authenticate: Payment ...` header: MPP Lightning charge challenge with a BOLT11 invoice (if MPP is enabled). - `Cache-Control: no-store` - `Content-Type: application/json` Response body (JSON): ```json { "error": "Payment Required", "detail": "This search requires payment of 1 xsr. Include a Cashu ecash token in the X-Cashu request header, or pay the Lightning invoice from the WWW-Authenticate header and retry with an Authorization header. See /skills.md for full payment instructions.", "skills_url": "/skills.md" } ``` **Bad request response (400):** Returned when the token cannot be parsed or the proofs are invalid. The response body is empty. ### `GET /info` Returns the mint URL for this service. ```json { "mint": "https://athenut.com" } ``` ### `GET /search_count` Returns the all-time search count. ```json { "all_time_search_count": 12345 } ``` ### Cashu Mint Protocol (`/v1/*`) Standard Cashu mint protocol endpoints are available under `/v1/` on the same host as the search API (i.e. `https://athenut.com/v1/*`). These include key discovery, minting, melting, swaps, and other NUT operations. Use these if your wallet needs to interact with the mint directly. ## Example (Cashu) ``` curl -H "X-Cashu: cashuBo2F0..." "https://athenut.com/search?q=what+is+cashu" ``` ## Example (MPP Lightning) ``` curl -H "Authorization: Payment eyJjaGFsbGVuZ2UiOns..." "https://athenut.com/search?q=what+is+cashu" ``` ## Important Details - Token must be worth exactly 1 xsr - no more, no less. - The unit is `xsr`, not `sat` or any other standard unit. - Tokens must be minted from `https://athenut.com`. - The `X-Cashu` header value is the raw token string (starting with `cashuB...`). - For MPP, the `Authorization` header carries a base64url-encoded JSON credential with the payment preimage. - For wallets without custom unit support, use the Lightning invoice flow instead. ## Concepts - **Cashu**: Privacy-preserving ecash protocol using blind signatures. - **Mint**: Server that issues and redeems Cashu tokens. This service runs a mint at `https://athenut.com`. - **xsr**: Custom Cashu unit representing one search result. 1 xsr = 1 search. - **Token**: A transferable Cashu string (starting with `cashuB...`) representing value. - **X-Cashu**: HTTP header used to carry Cashu payment requests (server to client) and payment tokens (client to server). - **MPP**: Machine Payments Protocol (https://mpp.dev/protocol) - an HTTP 402-based payment scheme using `WWW-Authenticate` and `Authorization` headers with support for multiple payment methods including Lightning. - **BOLT11**: Lightning Network invoice format used for MPP Lightning charge payments (https://mpp.dev/payment-methods/lightning). - **NUT-18**: Cashu protocol specification for payment requests. - **NUT-24**: Cashu protocol specification for HTTP 402 payment flow using the X-Cashu header. - **402 Payment Required**: HTTP status code indicating payment is needed before the request can be fulfilled.