fetcher
Shared payment and setup skill for fetcher.sh, a pay-per-call web-data API covering Twitter/X, TikTok, Instagram, YouTube, Reddit, Google Search, Google Maps, Google News, Google Play, the App Store, and Yelp. Use this skill whenever a task needs a fetcher.sh API key, a credit top-up, an x402 micropayment, MCP server configuration, or an explanation of the { status, message, data } response envelope and error codes — before or alongside any of the per-service skills (twitter-api, x-api, tiktok-api, instagram-api, youtube-api, reddit-api, google-search, google-maps, google-news, google-play, app-store, yelp). Also use it when the user asks how to pay with USDC, fund an agent wallet, set up credits, mint or rotate an API key, or connect an MCP client to fetcher.sh.
fetcher-sh · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add fetcher-sh/fetcher-skills --skill fetcherAbout this skill
name: fetcher description: >- Shared payment and setup skill for fetcher.sh, a pay-per-call web-data API covering Twitter/X, TikTok, Instagram, YouTube, Reddit, Google Search, Google Maps, Google News, Google Play, the App Store, and Yelp. Use this skill whenever a task needs a fetcher.sh API key, a credit top-up, an x402 micropayment, MCP server configuration, or an explanation of the { status, message, data } response envelope and error codes — before or alongside any of the per-service skills (twitter-api, x-api, tiktok-api, instagram-api, youtube-api, reddit-api, google-search, google-maps, google-news, google-play, app-store, yelp). Also use it when the user asks how to pay with USDC, fund an agent wallet, set up credits, mint or rotate an API key, or connect an MCP client to fetcher.sh. keywords:
- fetcher.sh
- x402
- usdc
- micropayments
- api-key
- credits
- mcp-server
- agent-payments
- crypto-payments
- base
- polygon
- arbitrum
- monad
- solana
fetcher.sh — payments, credits, and MCP setup
fetcher.sh is one HTTP gateway for 111 web-data endpoints across 11 services — Twitter/X, TikTok, Instagram, YouTube, Reddit, Google Search, Google Maps, Google News, Google Play, the App Store, and Yelp. Every endpoint is a plain GET, paid in USDC on Base, Polygon, Arbitrum, Monad, or Solana — per call via x402, or prepaid via credits with a Bearer API key. There is no signup form, no OAuth flow, and no API key waitlist.
Each service has its own skill (twitter-api, x-api,
tiktok-api, instagram-api, youtube-api, reddit-api,
google-search, google-maps, google-news, google-play, app-store,
yelp) with its own endpoint table and worked examples. This skill covers the
part that's identical across all of them: how to pay, how credits work, and
how to talk to fetcher.sh over MCP instead of raw HTTP.
Every service lives on its own subdomain (twitter.fetcher.sh,
tiktok.fetcher.sh, ...); fetcher.sh itself is the directory, the credits
balance, and the docs. Credits and the MCP server are identical on every host
— a key minted on one subdomain works on all of them.
Response envelope
Every endpoint, on every service, returns JSON of this shape:
{ "status": 200, "message": "ok", "data": "..." }
The HTTP status code mirrors the status field. Errors carry a descriptive
message.
Payment mode A — prepaid credits (recommended)
One on-chain payment funds a balance; every call after that is a plain HTTP request with an API key. This is the fastest path for an agent that will make more than one call — no signing, no chain round-trip per request.
Step 1 — top up (minimum $1). The top-up endpoint is itself x402-paid; pay it with any x402 client from a wallet holding USDC on Base, Polygon, Arbitrum, Monad, or Solana:
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
// Register every EVM chain you can pay from — the client picks whichever
// "accepts" entry matches. One EVM key signs on all of these.
const EVM_NETWORKS = ["eip155:8453", "eip155:137", "eip155:42161", "eip155:143"];
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
schemes: EVM_NETWORKS.map((network) => ({
network,
client: new ExactEvmScheme(account),
})),
});
const res = await fetchWithPayment(
"https://fetcher.sh/api/credits/topup?amount=5",
{ method: "POST" },
);
const { data } = await res.json();
// data.key -> "bby_live_..." — returned EXACTLY ONCE on the first top-up. Save it.
No wallet handy? A human can do this in the browser at
fetcher.sh/topup instead — connect an injected
wallet (MetaMask, Rabby, Talisman, Coinbase, or Phantom for Solana), pick a
chain, pay USDC, gas is sponsored. Ask the user to do that and hand you only
the resulting bby_live_... key; the key alone is sufficient for every data
call below.
Notes:
- Refill top-ups (calling the endpoint again on an existing wallet) keep the
existing key. Add
&rotate=1to mint a fresh one — the old key stops working immediately. - Lost keys cannot be recovered, only a hash is stored server-side — rotate instead of trying to reconstruct one.
- To add credits to an existing key from any wallet (not just the one that
minted it), send the same x402-paid
POSTwith the headerAuthorization: Bearer bby_live_...— the credit lands on that key's account instead of the payer's own balance.rotateis rejected in this mode, so refilling a deployed client never silently invalidates it. - Credits are keyed by wallet address, so an EVM wallet and a Solana wallet are two separate balances with two separate keys.
Step 2 — call any endpoint on any subdomain with the key:
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://twitter.fetcher.sh/api/search?query=hello"
Step 3 — check the balance whenever needed (Bearer-only):
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
"https://fetcher.sh/api/credits/balance"
If the balance can't cover a call, the API answers 402 with message
"topup_required" plus balance_micro, price_micro, and topup_url. Top up
again with the snippet above, then retry.
Payment mode B — x402 pay-per-call
Stateless and fully autonomous — no account, no key, no signup. Requirement: a wallet holding USDC on one of the supported networks. Gas is sponsored by the facilitator, so no native token is needed on any chain.
GETany endpoint with no payment →402response with a base64 payment-required header. Itsacceptsarray has one entry per active network, each with its own amount, USDC asset, and recipient. Base is always listed first. 2