Read what a coin's holders say, from your own code

The same reads /dd gives you on Discord and Telegram, as JSON. One call per coin returns what it is according to the people holding it, who they say is behind it, why they are in, and what argues against.

Get a key

1. Run /api in Discord, or in a private chat with the bot on Telegram.
2. Press Create key and give it a name. Copy the key straight away: it is shown once, and only a fingerprint of it is kept.
3. Send it with every request, as below.

Keys come with Pro and Max. A key belongs to the account that made it: one made on Discord spends that Discord account's plan, and one made on Telegram spends the Telegram account's. Each account can hold three keys at once. Keys start with srb_; one made before the bot was renamed starts with ddb_ and keeps working.

Authentication

Send the key as a bearer token on every request.

curl https://api.shadysresearchbot.com/v1/usage \
  -H "Authorization: Bearer srb_7Hq2kLm9xR4vTn8pWb3cYs6dFg1hJz5aQe0uNo"

Endpoints

Four endpoints, all GET. Only the coin report spends a read.

The full report, the same one the bot draws. A coin somebody has already read comes back at once from the store. One nobody has read yet is read now, which takes a while: the request waits up to 60 seconds and, if the read is still going, answers 202 with a job to poll.

curl https://api.shadysresearchbot.com/v1/coins/4kM2pB8cQyRZ3n5WdT1sHvLx6eJfGa9uN7Vqpump \
  -H "Authorization: Bearer $SRB_KEY"

{
  "report": {
    "address": "4kM2pB8cQyRZ3n5WdT1sHvLx6eJfGa9uN7Vqpump",
    "chain": "solana",
    "verdict": "clear",
    "headline": "A cat coin held for its community, with no product claimed.",
    "story": "Launched on pump.fun as a joke about ...",
    "utility": "",
    "team": "Holders say the dev is anonymous and has not sold.",
    "whyBuying": ["the community", "early holders are still in"],
    "concerns": ["no product", "one wallet holds a large share"],
    "links": [
      { "url": "https://x.com/...", "host": "x.com", "kind": "tweet", "count": 9, "authors": 7 }
    ],
    "callers": [ ... ],
    "stats": { "callers": 42, "distinctAuthors": 31, "medianPositionUsd": 380 },
    "cached": true,
    "generatedAt": "2026-10-08T15:02:11Z"
  },
  "quota": {
    "charged": true,
    "freeRepeat": false,
    "day": { "used": 7, "limit": 15 },
    "month": { "used": 59, "limit": 200 }
  }
}

{
  "status": "reading",
  "job": "job_9fQ2xLw4",
  "poll": "/v1/jobs/job_9fQ2xLw4",
  "retryAfter": 5
}

The holders who also posted, from pump.fun and FOMO, as the bot's Holders button shows them. Each row's rank is its place on that app's own list, not among every wallet on chain, so ranks of 1, 4 and 5 mean the 2nd and 3rd biggest positions never wrote a word. A snapshot stands for five minutes. Takes the same chain parameter.

{
  "address": "4kM2pB8cQyRZ3n5WdT1sHvLx6eJfGa9uN7Vqpump",
  "chain": "solana",
  "fetchedAt": "2026-10-08T15:04:00Z",
  "pumpfun": {
    "total": 590,
    "totalIs": "positions",
    "holders": [
      { "rank": 1, "handle": "catdad", "valueUsd": 4210, "thesis": "Here since 20k ..." }
    ]
  },
  "fomo": { "total": 212, "totalIs": "holders", "holders": [ ... ] }
}

Poll a read that was still going when /coins answered 202. While it runs you get 202 again, with retryAfter. When it is done you get exactly what /coins would have returned. The read is charged once, when it finishes, and a read that fails is never charged. Jobs are kept for 15 minutes.

Your plan, what is left, and when it comes back. Call it as often as you like: it only counts toward the speed limit.

{
  "account": { "platform": "discord", "plan": "pro", "expiresAt": "2026-11-08T14:02:00Z" },
  "day": { "used": 6, "limit": 15, "resetsAt": "2026-10-09T00:00:00Z" },
  "month": { "used": 58, "limit": 200, "resetsAt": "2026-10-21T09:14:00Z", "throughApi": 23 },
  "perMinute": { "limit": 10, "remaining": 9 },
  "keys": 2
}

What counts as a read

• One read per coin, per account, per day. Asking for a coin again the same day is free, wherever you read it first: /dd or the API, on the same account.
• A fresh read is always charged. fresh=true here, or Re-read in the bot, pays for a new read even on a coin you read today.
• A read that fails is never charged. If a coin cannot be placed or nothing could be read, nothing is taken.
• Holders, jobs and usage never spend a read. They only count toward the speed limit.
• Reads are shared with the bot. Pro's 200 a month is 200 between /dd and the API together.

A day ends at midnight UTC. A month is 30 days, counted from when you first bought your plan, and changing plan never restarts it.

Limits

The speed limit is per account, across all its keys. Every response says what is left, so you never have to guess:

X-Reads-Day-Remaining: 9
X-Reads-Month-Remaining: 142
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
Retry-After: 6              (only on a 429)

Errors

Every error is JSON, with a code to switch on and a sentence a person can read.

{
  "error": {
    "code": "DAILY_LIMIT",
    "message": "You have used today's 15 reads. They come back at midnight UTC.",
    "resetsAt": "2026-10-09T00:00:00Z"
  }
}

Use it from an AI agent

The API is also an MCP server, so Claude and other agents can read coins for you with the same key, the same reads and the same limits. Seven tools; only read_coin spends a read, and only tool calls count toward the speed limit. An agent waits out a fresh read itself, so there is no job to poll.

Connect me to Shady's Research Bot, an MCP server that reads what a coin's holders say about it.

  Name:       shadysresearchbot
  Transport:  Streamable HTTP
  URL:        https://api.shadysresearchbot.com/mcp
  Header:     Authorization: Bearer srb_YOUR_KEY

If you are Claude Code, Cursor, Codex or another client that can edit its own config, add it yourself:
  Claude Code:  claude mcp add --transport http --scope user shadysresearchbot https://api.shadysresearchbot.com/mcp --header "Authorization: Bearer srb_YOUR_KEY"
  mcp.json:     {"mcpServers": {"shadysresearchbot": {"type": "http", "url": "https://api.shadysresearchbot.com/mcp", "headers": {"Authorization": "Bearer srb_YOUR_KEY"}}}}
Then call its get_usage tool and tell me which plan I am on and how many reads I have left today.

If you are claude.ai or Claude Desktop, you cannot add connectors yourself, so walk me through it step by step:
  1. Open Customize, then Connectors, press + Add, then Add custom connector.
  2. Name: Shady's Research Bot
  3. URL: https://api.shadysresearchbot.com/mcp/srb_YOUR_KEY
  4. Authentication: No sign-in. Leave every OAuth field empty.
  5. Add it, start a new chat, and ask me to call get_usage.
That URL carries my key, so treat it like a password.

Do not commit the key or write it into any file tracked by git.

Paste it into Claude Code, Cursor or Codex and the agent adds the server itself, then calls get_usage. Paste it into claude.ai or Claude Desktop and Claude walks you through adding it as a custom connector. Replace ddb_YOUR_KEY with your key: the Key created screen in the bot shows this prompt with your key already in it.

claude.ai and Claude Desktop

1. Open Customize, then Connectors, press + Add, then Add custom connector.
2. Name: Shady's Research Bot
3. URL: your personal connector URL
4. Authentication: No sign-in. Leave every OAuth field empty.
5. Add it, start a new chat, and ask Claude to call get_usage.

Your personal connector URL is https://api.shadysresearchbot.com/mcp/<your key>. The key rides in the address because those apps cannot send a header without a sign-in flow, so treat the URL like a password. Revoking the key from /api kills it at once, and a bad or revoked key answers 401. GET and DELETE on it answer 405.

By hand

claude mcp add --transport http --scope user shadysresearchbot https://api.shadysresearchbot.com/mcp --header "Authorization: Bearer srb_YOUR_KEY"

{
  "mcpServers": {
    "shadysresearchbot": {
      "type": "http",
      "url": "https://api.shadysresearchbot.com/mcp",
      "headers": {
        "Authorization": "Bearer srb_YOUR_KEY"
      }
    }
  }
}

The tools

A refused tool call is a result the agent can read, not a transport error: a JSON body with code and message, the same codes as above, plus NOT_READ for coin_links and coin_sources on a coin this account has not read yet, and BAD_QUERY for a find_coin query it cannot search. A bad key is still 401 before anything runs.