# API documentation — no account, pay per call

> 111 read-only endpoints across 11 services, $0.002 – $0.005 per call in USDC on Base, Polygon, Arbitrum, Monad or Solana. No account, no OAuth, no subscription — you pay per call, starting at $0.002. Each service is its own API on its own host.

- Base URL: `https://<service>.fetcher.sh/api/...`
- Method: GET · JSON envelope
- Catalog: https://fetcher.sh/llms.txt
- Agent setup: https://fetcher.sh/skill.md
- OpenAPI 3.1: https://fetcher.sh/openapi.json
- MCP: https://mcp.fetcher.sh

## Quick start

Prepaid credits (simplest for code):

```bash
curl -H 'Authorization: Bearer bby_live_...' \
  'https://twitter.fetcher.sh/api/search?query=x402'
```

Get a key at https://fetcher.sh/topup — the first top-up creates it (minimum $1, shown once).

Pay per call with x402:

```bash
# call without payment to inspect the 402 challenge
curl -i 'https://twitter.fetcher.sh/api/search?query=x402'
# HTTP/1.1 402 Payment Required
# payment-required: <base64 payment requirements>
```

Sign the requirements from the `payment-required` header and retry. Libraries such as `@x402/fetch` do the loop — see https://fetcher.sh/skill.md.

## Authentication

There are no accounts. Either a signed payment or an API key authenticates the request.

- **Credits API key** — `Authorization: Bearer bby_live_…`. Each call debits the balance. Keys are shown once; a lost key can only be rotated at https://fetcher.sh/topup.
- **x402 payment** — no key. The signed USDC authorization in `X-Payment` is the credential. Every 402 lists one option per chain on Base, Polygon, Arbitrum, Monad or Solana. Gas is sponsored.

Check a balance with `GET /api/credits/balance` and the same Bearer header.

## Response format

Every endpoint returns the same envelope; the HTTP status mirrors the `status` field. Upstream payloads arrive untouched in `data`.

```json
{
  "status": 200,
  "message": "ok",
  "data": { }
}
```

## Errors

- 400 — a parameter is missing or invalid; the message names it
- 401 — unknown or revoked API key
- 402 — payment required (x402 challenge) or `topup_required` when a prepaid balance is exhausted
- 404 — the path is not a priced endpoint
- 502 — the upstream source failed or was unreachable

## Limits and refunds

No rate limits and no quotas — your balance or wallet is the only ceiling. Payment settles before delivery, so a failed upstream call is not refunded.

## MCP server

Add the remote server to Claude Desktop, Cursor, or any MCP client:

```json
{
  "mcpServers": {
    "fetcher": {
      "url": "https://mcp.fetcher.sh",
      "headers": { "Authorization": "Bearer bby_live_..." }
    }
  }
}
```

Drop the header to pay per call with x402 instead.

## Endpoint reference

### Twitter / X (15 · $0.002 – $0.005)

Host: https://twitter.fetcher.sh

- [Handle](https://twitter.fetcher.sh/handle.md) — GET /api/handle/{handle} — $0.005
- [Handle about](https://twitter.fetcher.sh/handle-about.md) — GET /api/handle/{handle}/about — $0.005
- [List members](https://twitter.fetcher.sh/list-members.md) — GET /api/list/{id}/members — $0.005
- [List tweets](https://twitter.fetcher.sh/list-tweets.md) — GET /api/list/{id}/tweets — $0.005
- [Search](https://twitter.fetcher.sh/search.md) — GET /api/search — $0.005
- [Search users](https://twitter.fetcher.sh/search-users.md) — GET /api/search/users — $0.005
- [Trends](https://twitter.fetcher.sh/trends.md) — GET /api/trends — $0.005
- [Tweet](https://twitter.fetcher.sh/tweet.md) — GET /api/tweet/{id} — $0.002
- [Tweet replies](https://twitter.fetcher.sh/tweet-replies.md) — GET /api/tweet/{id}/replies — $0.005
- [Tweet retweeters](https://twitter.fetcher.sh/tweet-retweeters.md) — GET /api/tweet/{id}/retweeters — $0.005
- [User](https://twitter.fetcher.sh/user.md) — GET /api/user/{id} — $0.005
- [User followers](https://twitter.fetcher.sh/user-followers.md) — GET /api/user/{id}/followers — $0.005
- [User followings](https://twitter.fetcher.sh/user-followings.md) — GET /api/user/{id}/followings — $0.005
- [User replies](https://twitter.fetcher.sh/user-replies.md) — GET /api/user/{id}/replies — $0.005
- [User tweets](https://twitter.fetcher.sh/user-tweets.md) — GET /api/user/{id}/tweets — $0.005

### YouTube (15 · $0.005)

Host: https://youtube.fetcher.sh

- [Channel handle](https://youtube.fetcher.sh/channel-handle.md) — GET /api/channel/handle/{handle} — $0.005
- [Channel path](https://youtube.fetcher.sh/channel-path.md) — GET /api/channel/path — $0.005
- [Channel](https://youtube.fetcher.sh/channel.md) — GET /api/channel/{id} — $0.005
- [Channel live streams](https://youtube.fetcher.sh/channel-live-streams.md) — GET /api/channel/{id}/live-streams — $0.005
- [Channel shorts](https://youtube.fetcher.sh/channel-shorts.md) — GET /api/channel/{id}/shorts — $0.005
- [Channel videos](https://youtube.fetcher.sh/channel-videos.md) — GET /api/channel/{id}/videos — $0.005
- [Hashtag](https://youtube.fetcher.sh/hashtag.md) — GET /api/hashtag/{tag} — $0.005
- [Playlist videos](https://youtube.fetcher.sh/playlist-videos.md) — GET /api/playlist/{id}/videos — $0.005
- [Search channel](https://youtube.fetcher.sh/search-channel.md) — GET /api/search/channel — $0.005
- [Search playlist](https://youtube.fetcher.sh/search-playlist.md) — GET /api/search/playlist — $0.005
- [Search video](https://youtube.fetcher.sh/search-video.md) — GET /api/search/video — $0.005
- [Shorts](https://youtube.fetcher.sh/shorts.md) — GET /api/shorts/{id} — $0.005
- [Trending](https://youtube.fetcher.sh/trending.md) — GET /api/trending — $0.005
- [Video](https://youtube.fetcher.sh/video.md) — GET /api/video/{id} — $0.005
- [Video comments](https://youtube.fetcher.sh/video-comments.md) — GET /api/video/{id}/comments — $0.005

### TikTok (13 · $0.004)

Host: https://tiktok.fetcher.sh

- [Hashtag handle](https://tiktok.fetcher.sh/hashtag-handle.md) — GET /api/hashtag/handle/{name} — $0.004
- [Hashtag posts](https://tiktok.fetcher.sh/hashtag-posts.md) — GET /api/hashtag/{id}/posts — $0.004
- [Location posts](https://tiktok.fetcher.sh/location-posts.md) — GET /api/location/{locationId}/posts — $0.004
- [Music posts](https://tiktok.fetcher.sh/music-posts.md) — GET /api/music/{id}/posts — $0.004
- [Post](https://tiktok.fetcher.sh/post.md) — GET /api/post — $0.004
- [Post search](https://tiktok.fetcher.sh/post-search.md) — GET /api/post/search — $0.004
- [Post](https://tiktok.fetcher.sh/post-by-id.md) — GET /api/post/{id} — $0.004
- [Post comments](https://tiktok.fetcher.sh/post-comments.md) — GET /api/post/{id}/comments — $0.004
- [Post comments replies](https://tiktok.fetcher.sh/post-comments-replies.md) — GET /api/post/{id}/comments/{commentId}/replies — $0.004
- [User handle](https://tiktok.fetcher.sh/user-handle.md) — GET /api/user/handle/{username} — $0.004
- [User followers](https://tiktok.fetcher.sh/user-followers.md) — GET /api/user/{id}/followers — $0.004
- [User followings](https://tiktok.fetcher.sh/user-followings.md) — GET /api/user/{id}/followings — $0.004
- [User posts](https://tiktok.fetcher.sh/user-posts.md) — GET /api/user/{id}/posts — $0.004

### Instagram (16 · $0.004)

Host: https://instagram.fetcher.sh

- [Audio posts](https://instagram.fetcher.sh/audio-posts.md) — GET /api/audio/{id}/posts — $0.004
- [Hashtag posts](https://instagram.fetcher.sh/hashtag-posts.md) — GET /api/hashtag/{name}/posts — $0.004
- [Hashtag reels](https://instagram.fetcher.sh/hashtag-reels.md) — GET /api/hashtag/{name}/reels — $0.004
- [Location posts](https://instagram.fetcher.sh/location-posts.md) — GET /api/location/{id}/posts — $0.004
- [Post code](https://instagram.fetcher.sh/post-code.md) — GET /api/post/code/{code} — $0.004
- [Post comments](https://instagram.fetcher.sh/post-comments.md) — GET /api/post/{id}/comments — $0.004
- [User handle](https://instagram.fetcher.sh/user-handle.md) — GET /api/user/handle/{handle} — $0.004
- [User search](https://instagram.fetcher.sh/user-search.md) — GET /api/user/search — $0.004
- [User](https://instagram.fetcher.sh/user.md) — GET /api/user/{id} — $0.004
- [User followers](https://instagram.fetcher.sh/user-followers.md) — GET /api/user/{id}/followers — $0.004
- [User followings](https://instagram.fetcher.sh/user-followings.md) — GET /api/user/{id}/followings — $0.004
- [User posts](https://instagram.fetcher.sh/user-posts.md) — GET /api/user/{id}/posts — $0.004
- [User posts tagged](https://instagram.fetcher.sh/user-posts-tagged.md) — GET /api/user/{id}/posts/tagged — $0.004
- [User reels](https://instagram.fetcher.sh/user-reels.md) — GET /api/user/{id}/reels — $0.004
- [User stories](https://instagram.fetcher.sh/user-stories.md) — GET /api/user/{id}/stories — $0.004
- [Userid](https://instagram.fetcher.sh/userid.md) — GET /api/userid/{handle} — $0.004

### Reddit (15 · $0.002)

Host: https://reddit.fetcher.sh

- [Post](https://reddit.fetcher.sh/post.md) — GET /api/post/{id} — $0.002
- [Post comments](https://reddit.fetcher.sh/post-comments.md) — GET /api/post/{id}/comments — $0.002
- [Post comments replies](https://reddit.fetcher.sh/post-comments-replies.md) — GET /api/post/{id}/comments/{commentId}/replies — $0.002
- [Posts best](https://reddit.fetcher.sh/posts-best.md) — GET /api/posts/best — $0.002
- [Posts hot](https://reddit.fetcher.sh/posts-hot.md) — GET /api/posts/hot — $0.002
- [Posts new](https://reddit.fetcher.sh/posts-new.md) — GET /api/posts/new — $0.002
- [Posts top](https://reddit.fetcher.sh/posts-top.md) — GET /api/posts/top — $0.002
- [Search post](https://reddit.fetcher.sh/search-post.md) — GET /api/search/post — $0.002
- [Search subreddit](https://reddit.fetcher.sh/search-subreddit.md) — GET /api/search/subreddit — $0.002
- [Search user](https://reddit.fetcher.sh/search-user.md) — GET /api/search/user — $0.002
- [Subreddit](https://reddit.fetcher.sh/subreddit.md) — GET /api/subreddit/{name} — $0.002
- [Subreddit posts](https://reddit.fetcher.sh/subreddit-posts.md) — GET /api/subreddit/{name}/posts — $0.002
- [User](https://reddit.fetcher.sh/user.md) — GET /api/user/{username} — $0.002
- [User comments](https://reddit.fetcher.sh/user-comments.md) — GET /api/user/{username}/comments — $0.002
- [User posts](https://reddit.fetcher.sh/user-posts.md) — GET /api/user/{username}/posts — $0.002

### Google Search (1 · $0.005)

Host: https://google.fetcher.sh

- [Search](https://google.fetcher.sh/search.md) — GET /api/search — $0.005

### Google Maps (4 · $0.005)

Host: https://google-maps.fetcher.sh

- [Place search](https://google-maps.fetcher.sh/place-search.md) — GET /api/place/search — $0.005
- [Place](https://google-maps.fetcher.sh/place.md) — GET /api/place/{fid} — $0.005
- [Place reviews](https://google-maps.fetcher.sh/place-reviews.md) — GET /api/place/{fid}/reviews — $0.005
- [Review](https://google-maps.fetcher.sh/review.md) — GET /api/review/{id} — $0.005

### Google News (12 · $0.005)

Host: https://google-news.fetcher.sh

- [Business](https://google-news.fetcher.sh/business.md) — GET /api/business — $0.005
- [Decode article URL](https://google-news.fetcher.sh/decode-article-url.md) — GET /api/decode-article-url — $0.005
- [Entertainment](https://google-news.fetcher.sh/entertainment.md) — GET /api/entertainment — $0.005
- [Health](https://google-news.fetcher.sh/health.md) — GET /api/health — $0.005
- [Language regions](https://google-news.fetcher.sh/language-regions.md) — GET /api/language-regions — $0.005
- [Latest](https://google-news.fetcher.sh/latest.md) — GET /api/latest — $0.005
- [Science](https://google-news.fetcher.sh/science.md) — GET /api/science — $0.005
- [Search](https://google-news.fetcher.sh/search.md) — GET /api/search — $0.005
- [Sport](https://google-news.fetcher.sh/sport.md) — GET /api/sport — $0.005
- [Technology](https://google-news.fetcher.sh/technology.md) — GET /api/technology — $0.005
- [Topic](https://google-news.fetcher.sh/topic.md) — GET /api/topic/{topicId} — $0.005
- [World](https://google-news.fetcher.sh/world.md) — GET /api/world — $0.005

### Google Play (7 · $0.003)

Host: https://googleplay.fetcher.sh

- [Apps](https://googleplay.fetcher.sh/apps.md) — GET /api/apps — $0.003
- [Apps](https://googleplay.fetcher.sh/apps-by-appid.md) — GET /api/apps/{appId} — $0.003
- [Apps datasafety](https://googleplay.fetcher.sh/apps-datasafety.md) — GET /api/apps/{appId}/datasafety — $0.003
- [Apps permissions](https://googleplay.fetcher.sh/apps-permissions.md) — GET /api/apps/{appId}/permissions — $0.003
- [Apps reviews](https://googleplay.fetcher.sh/apps-reviews.md) — GET /api/apps/{appId}/reviews — $0.003
- [Apps similar](https://googleplay.fetcher.sh/apps-similar.md) — GET /api/apps/{appId}/similar — $0.003
- [Developers](https://googleplay.fetcher.sh/developers.md) — GET /api/developers/{developerId} — $0.003

### App Store (9 · $0.003)

Host: https://appstore.fetcher.sh

- [Apps](https://appstore.fetcher.sh/apps.md) — GET /api/apps — $0.003
- [Apps](https://appstore.fetcher.sh/apps-by-appid.md) — GET /api/apps/{appId} — $0.003
- [Apps reviews](https://appstore.fetcher.sh/apps-reviews.md) — GET /api/apps/{appId}/reviews — $0.003
- [Apps similar](https://appstore.fetcher.sh/apps-similar.md) — GET /api/apps/{appId}/similar — $0.003
- [Bundles](https://appstore.fetcher.sh/bundles.md) — GET /api/bundles — $0.003
- [Bundles](https://appstore.fetcher.sh/bundles-by-bundleid.md) — GET /api/bundles/{bundleId} — $0.003
- [Bundles reviews](https://appstore.fetcher.sh/bundles-reviews.md) — GET /api/bundles/{bundleId}/reviews — $0.003
- [Bundles similar](https://appstore.fetcher.sh/bundles-similar.md) — GET /api/bundles/{bundleId}/similar — $0.003
- [Developers](https://appstore.fetcher.sh/developers.md) — GET /api/developers/{developerId} — $0.003

### Yelp (4 · $0.003)

Host: https://yelp.fetcher.sh

- [Place handle](https://yelp.fetcher.sh/place-handle.md) — GET /api/place/handle/{handle} — $0.003
- [Place](https://yelp.fetcher.sh/place.md) — GET /api/place/{id} — $0.003
- [Place reviews](https://yelp.fetcher.sh/place-reviews.md) — GET /api/place/{id}/reviews — $0.003
- [Search](https://yelp.fetcher.sh/search.md) — GET /api/search — $0.003