Developers

Firsay API, CLI and MCP

Everything you can do on firsay.io works from code and AI agents: describe who you need in plain words and get people with proof and public contacts. Searches use your plan limits, and a search that finds nothing is not counted.

1. API key 2. Search endpoint 3. Response 4. Errors and limits 5. CLI 6. MCP for agents

1. Get an API key

Sign in on firsay.io, open Account → API keys & MCP and create a key. It starts with fsy_ and is shown once. Keep it secret: anyone with the key searches on your plan. You can revoke a key at any time on the same screen.

2. Search

POST https://firsay.io/api/run with the key in the Authorization header.

curl https://firsay.io/api/run \
  -H "Authorization: Bearer fsy_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskText": "Find 10 BD managers at crypto exchanges on Telegram", "targetCount": 10}'

Field	Type	Meaning
`taskText`	string, required	Who you need, in plain words. Roles, projects, chains, countries and follower ranges are understood.
`targetCount`	integer	How many results you want (capped by your plan: 10, 25 or 50).
`freshOnly`	boolean	Default `true`: skip people you have already received.
`recency`	integer, days	How recent the activity or posts should be (1 to 90, default 30).

JavaScript

const response = await fetch('https://firsay.io/api/run', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.FIRSAY_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ taskText: 'Who is the founder of Jupiter', targetCount: 10 })
});
const { candidates } = await response.json();

Python

import os, requests
r = requests.post("https://firsay.io/api/run",
    headers={"Authorization": f"Bearer {os.environ['FIRSAY_API_KEY']}"},
    json={"taskText": "Find projects that need KOLs right now", "targetCount": 10}, timeout=180)
for person in r.json()["candidates"]:
    print(person["person"], person["role"], person.get("telegram"))

A search takes from a few seconds (Telegram index) to about a minute (live X research). Use a timeout of at least 180 seconds.

3. Response

{
  "ok": true,
  "runId": "run_...",
  "candidates": [
    {
      "person": "@RomDotSol",
      "displayName": "Rom",
      "role": "BD Lead",
      "project": "Jupiter",
      "source": "X/Twitter",
      "xProfile": "https://x.com/RomDotSol",
      "telegram": "",
      "email": "",
      "website": "",
      "evidence": "Own X BIO: \"Institutional BD @JupiterExchange\" ...",
      "notes": "Current role at this project stated in own X BIO.",
      "score": 95
    }
  ],
  "metrics": { "candidates": 1, "usage": { "used": 3, "limit": 25 } }
}

Field	Meaning
`person`, `displayName`	Handle and name.
`role`, `project`	The role and project Firsay found.
`evidence`	Why Firsay believes it: the BIO line, official post, X affiliate badge, Telegram admin title or chat message.
`telegram`, `xProfile`, `email`, `website`	Public contacts, only when published by the person or project.
`source`, `sourceUrl`	Where the result came from and a link to check it.
`score`	Confidence from 0 to 100.

4. Errors and limits

Status	Meaning
401	Missing or revoked API key.
422 `needs_detail`	The request is too vague (for example "hello"). Nothing was counted.
429	Plan limit or rate limit reached (12 searches a minute). The response says when it resets.
503	A data source is temporarily unavailable. Retry later; nothing was counted.

5. CLI

No install, Node 18 or newer. Download firsay-cli.js and run:

FIRSAY_API_KEY=fsy_YOUR_KEY node firsay-cli.js search "Find 10 KOLs who post about Solana"
FIRSAY_API_KEY=fsy_YOUR_KEY node firsay-cli.js search "Find ZK projects" --count 20 --json

6. MCP for Claude, Cursor and other agents

Firsay is a remote MCP server with one tool, firsay_search. Nothing to install: connect by URL with your API key.

URL:    https://firsay.io/api/mcp
Header: Authorization: Bearer fsy_YOUR_KEY

Claude Code:

claude mcp add --transport http firsay https://firsay.io/api/mcp --header "Authorization: Bearer fsy_YOUR_KEY"

Cursor, Windsurf and other clients with remote MCP support (mcp.json):

{
  "mcpServers": {
    "firsay": {
      "url": "https://firsay.io/api/mcp",
      "headers": { "Authorization": "Bearer fsy_YOUR_KEY" }
    }
  }
}

Clients that only run local servers can use the CLI file instead:

{
  "mcpServers": {
    "firsay": {
      "command": "node",
      "args": ["/path/to/firsay-cli.js", "mcp"],
      "env": { "FIRSAY_API_KEY": "fsy_YOUR_KEY" }
    }
  }
}

Then ask in plain words, for example: "Use Firsay to find 20 market makers for a new token listing and draft a message to each."

Questions or a missing feature: t.me/firsayai.