@fetcher-sh/api

The developer-friendly client for fetcher.sh — 111 pay-per-call web-data endpoints across Twitter/X, YouTube, TikTok, Instagram, Reddit, Google Search, Google Maps, Google News, Google Play, the App Store, and Yelp. Use it as an NPM library or a CLI.

Every endpoint is a plain GET returning a stable { status, message, data } envelope. Pay per call in USDC via x402, or top up once and spend a single prepaid balance across all 11 services — the same bby_live_ key works everywhere.

Prerequisites

• Node.js 18+ (uses the built-in fetch).
• One of:
  • A prepaid API key (bby_live_...) — get one at fetcher.sh/topup, or
  • A wallet holding a few cents of USDC on Base, Polygon, Arbitrum, Monad, or Solana, for pay-per-call x402 (no key needed).

Installation

npm install @fetcher-sh/api

Quick start (library)

// ESM
import { Fetcher } from "@fetcher-sh/api";

// CommonJS
const { Fetcher } = require("@fetcher-sh/api");

const fetcher = new Fetcher({ apiKey: process.env.FETCHER_API_KEY });

// Search tweets
const tweets = await fetcher.twitter.search({ query: "x402" });

// Look up an Instagram profile by handle
const profile = await fetcher.instagram.userByHandle("nasa");

// Clean Google web-search results
const serp = await fetcher.google.search({ query: "climate change" });

console.log(tweets, profile, serp);

By default every method returns just the data field. Pass { fullResponse: true } to get the whole { status, message, data } envelope.

const env = await fetcher.reddit.searchPosts(
  { query: "bitcoin" },
  { fullResponse: true },
);
console.log(env.status, env.message, env.data);

If the apiKey is omitted it falls back to the FETCHER_API_KEY environment variable.

Services & methods

One balance, eleven services. Each namespace maps 1:1 to the endpoints in the live catalog.

The generic escape hatch

Any endpoint — even ones without a named helper — is reachable with get:

await fetcher.get("/api/twitter/search", { params: { query: "x402" } });
await fetcher.get("/api/reddit/subreddit/programming/posts");

Pagination

Paginated endpoints return an opaque cursor. Pass it back to fetch the next page:

let cursor: string | undefined;
do {
  const page = await fetcher.twitter.userFollowers("44196397", {
    fullResponse: true,
    params: { cursor },
  });
  // ...process page.data...
  cursor = (page.data as any)?.cursor;
} while (cursor);

Paying per call with x402 (no key)

Skip the API key and pass a payment-wrapped fetch instead. The client stays dependency-free — you bring the wallet:

import { Fetcher } from "@fetcher-sh/api";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: ["eip155:8453", "eip155:137", "eip155:42161", "eip155:143"].map(
    (network) => ({ network, client: new ExactEvmScheme(account) }),
  ),
});

const fetcher = new Fetcher({ fetch: fetchWithPayment });
const tweets = await fetcher.twitter.search({ query: "x402" }); // 402 → sign → retry, automatically

Gas is sponsored, so the wallet needs no native token — just USDC on any supported chain.

Credits

// Read the shared balance (needs an API key)
const balance = await fetcher.credits.balance();
console.log(balance.balance_usd);

// Top up (x402-paid; requires a payment-wrapped fetch). The first top-up
// returns the bby_live_ key EXACTLY ONCE — store it, it cannot be recovered.
const result = await fetcher.credits.topup(5);
console.log(result.key);

Error handling

Every non-2xx response throws a FetcherError carrying the status, parsed envelope, and helpers:

import { FetcherError } from "@fetcher-sh/api";

try {
  await fetcher.twitter.search({ query: "x402" });
} catch (err) {
  if (err instanceof FetcherError) {
    if (err.isTopupRequired) console.error("Out of credits — top up.");
    else if (err.isUnauthorized) console.error("Bad or rotated API key.");
    else if (err.isPaymentRequired) console.error("x402 payment required.");
    else console.error(err.status, err.message);
  }
}

CLI

Install globally to use from the command line:

npm install -g @fetcher-sh/api

Setup

# Store your API key (saved to ~/.fetcher-sh/config.json)
fetcher init --token bby_live_xxx

# Or set it as an environment variable
export FETCHER_API_KEY=bby_live_xxx

# Or pass it per command
fetcher balance --token bby_live_xxx

Commands

# Shortcuts for each service's hero endpoint
fetcher twitter-search "x402"
fetcher youtube-search "lofi hip hop"
fetcher tiktok-search "cats"
fetcher instagram-user nasa
fetcher reddit-search "bitcoin"
fetcher google-search "climate change"
fetcher google-maps-search "coffee near me"
fetcher google-news-search "artificial intelligence"
fetcher googleplay-apps "notes"
fetcher appstore-apps "notes"
fetcher yelp-search "coffee" --location "San Francisco"

# Call ANY endpoint by path; extra --flags become query params
fetcher get /api/twitter/user/44196397/tweets --cursor abc123
fetcher get /api/reddit/subreddit/programming/posts

# Credits
fetcher balance
fetcher topup --amount 5          # needs an x402 wallet — see notes

# Explore the catalog
fetcher services
fetcher endpoints twitter

Output options

fetcher twitter-search "x402"              # pretty JSON (default)
fetcher twitter-search "x402" --json       # compact JSON
fetcher twitter-search "x402" --jsonl      # one object per line (arrays)
fetcher twitter-search "x402" --output out.json
fetcher get /api/x/y --debug               # show raw error bodies

Global flags

API reference

new Fetcher(options?)

Request options (per call)

Statics

• Fetcher.endpoints() — the full catalog of 111 priced endpoints.
• Fetcher.services() — per-service metadata (host, count, summary).
• Fetcher.priceOf(path) — USD price for a path (templated paths supported).

Notes

• Read-only by design. Every endpoint is a GET — no writes, follows, or posts.
• No rate limits. Your balance (or wallet) is the natural backpressure.
• No refunds on upstream failure. Settlement precedes delivery.
• This is an unofficial client for fetcher.sh, which itself is an independent proxy with no affiliation to X, TikTok, Meta, Google, Yelp, or Apple.

License

MIT