---
name: replynodes-fetcher-api
display_name: ReplyNodes Web Data APIs (Fetcher Gateway)
version: v1
contract_version: v1
mode: readonly
auth: bearer API key (rn_live_...) or x402 pay-per-call (USDC on Base)
gateway: https://api.replynodes.com
---

# ReplyNodes Web Data APIs

Read-only, normalized public web-data reads exposed through the ReplyNodes
fetcher gateway at `https://api.replynodes.com`. One API key = one account =
one prepaid credit balance. Agents pay per call in USDC on Base (x402 v2) or
burn prepaid credits with a bearer key — there is no signup flow and no
monthly plan.

Every cataloged operation is an HTTP GET against public platform data.
No write, publish, or authenticated-user path exists on this boundary.

## Payment model

- **Prepaid credits (primary).** Start at `https://platform.replynodes.com/payment`
  with a short-lived Base Mainnet USDC x402 onboarding intent. The API key is
  created only after facilitator verification and settlement; balance is stored in micros
  ($1 = 1,000,000).
- **x402 pay-per-call (no account).** Call any metered endpoint without auth →
  `402` with machine-readable requirements (scheme `exact`, network
  `eip155:8453` / Base, asset USDC). Retry with an `X-PAYMENT` header; a
  successful response carries an `X-PAYMENT-RESPONSE` settlement header. A
  failed request never settles and never charges.
- **Free tier.** Fresh keys include a small daily free-call allowance for
  evaluation.
- **Debit timing.** Settle-before-delivery: credits are debited only when the
  read succeeds. There are no refunds after successful delivery.

## Metered prices today

| Endpoint | Price |
| --- | --- |
| `GET /v1/x/users/{handle}/posts` | $0.05 / call |
| `GET /v1/x/posts/{post_id}` | $0.01 / call |
| `GET /v1/appstore/*` (app, list, search, developer, privacy, suggest, similar, reviews, ratings) | $0.003 / call |
| `GET /v1/youtube/*` (search, video, channel, comments, playlist, related, transcript) | $0.003 / call |

The current ClawHub provider skills cover these live read-data surfaces:
X, Instagram, Reddit, Hacker News, App Store, YouTube, Google Play, and Fomo App.
Route availability and pricing remain operation-specific; inspect the provider
capabilities reference before calling a route.

## Authentication

Send every metered request with `Authorization: Bearer rn_live_...`.
Keys are minted during top-up checkout, shown exactly once, and stored only as
SHA-256 hashes — treat them as secrets and never embed them client-side.
A lost key cannot be recovered; rotate by minting a new one.

## Core endpoints

```
GET https://api.replynodes.com/v1/x/capabilities        # free · route table + provider status
GET https://api.replynodes.com/v1/x/users/{handle}/posts?cursor=   # $0.05 · page of posts
GET https://api.replynodes.com/v1/x/posts/{post_id}     # $0.01 · single post
GET https://api.replynodes.com/v1/appstore/capabilities # free · route table + provider status
GET https://api.replynodes.com/v1/appstore/app?id=...   # $0.003 · app details
GET https://api.replynodes.com/v1/youtube/capabilities  # free · route table + provider status
GET https://api.replynodes.com/v1/youtube/video/{id}    # $0.003 · video details
GET https://api.replynodes.com/v1/me/balance            # free · remaining micros for your key
GET https://api.replynodes.com/healthz                  # free · liveness
GET https://api.replynodes.com/.well-known/x402.json    # free · x402 discovery manifest
```

## Success envelope

```json
{
  "data": [{ "id": "x:post:...", "text": "...", "created_at": "..." }],
  "meta": { "request_id": "req-...", "next_cursor": "..." }
}
```

- Pass `meta.next_cursor` back as `?cursor=` verbatim to paginate; null ends
  the collection; bad cursors fail closed with `400 invalid_cursor`.
- `meta.stale: true` marks cache-fallback payloads served during upstream
  incidents — treat as potentially outdated.

## Errors

Every non-2xx body is `{ "error": { "code", "message", "request_id" } }`.
The billing-specific ones:

| HTTP | Code | Meaning |
| --- | --- | --- |
| 401 | `unauthorized` / `invalid_key` | Missing or unknown bearer key. |
| 402 | `topup_required` | Insufficient balance. Body carries `balance_micro`, `price_micro`, `topup_url`. Recovery: check `/v1/me/balance` → use the explicit x402 onboarding/top-up intent flow → retry. |
| 429 | `rate_limited` | Protective window hit (60/min per key, 300/min per org default). Honor `Retry-After`. |

## MCP (coming soon)

A remote MCP server will be exposed over streamable HTTP at
`https://api.replynodes.com/mcp`. Planned config:

```json
{
  "mcpServers": {
    "replynodes": { "url": "https://api.replynodes.com/mcp" }
  }
}
```

With credits instead of x402:

```json
{
  "mcpServers": {
    "replynodes": {
      "url": "https://api.replynodes.com/mcp",
      "headers": { "Authorization": "Bearer rn_live_..." }
    }
  }
}
```

Planned tools: `search_endpoints`, `describe_endpoint`, `check_balance`
(free); `fetch_data(provider, op, params)`, named per-provider shortcuts such
as `x_list_user_posts` and `x_get_post`, and `topup_credits` (paid). The MCP
server is not live yet; REST and x402 work today.

## Machine-readable artifacts

- `https://replynodes.com/api/openapi/` — verified OpenAPI publication status; no OpenAPI document is published yet
- `https://platform.replynodes.com/payment.json` — programmatic top-up/balance flows
- `https://platform.replynodes.com/llms.txt` — site summary for LLM agents
- This file (`https://platform.replynodes.com/skill.md`) — agent setup handbook

## Guarantees

- GET-only public data; no mutations exist now or later.
- No platform login material is held or accepted; no customer-managed
  platform developer credentials required.
- Single chain: Base. Multi-chain support is out of scope for v1.