# Flashpoint.AI

> Primary research data on demand — surveys, synthetic respondents, demographics, and AI-powered analysis.
> Site: https://flashpoint.ai
> Docs: https://docs.flashpoint.ai
> Full corpus: https://docs.flashpoint.ai/llms-full.txt

## What this is

Flashpoint.AI runs primary research: design surveys, recruit panels (real or
synthetic), field, analyze, deliver — by asking. The same surface serves
human researchers (chat at app.flashpoint.ai) and autonomous agents (MCP +
x402 pay-per-call). No survey software to learn.

## How it works

Every tool is callable over MCP using x402 — no API keys, no accounts.
Your agent connects to our MCP server, sends a `tools/call`, gets a 402
challenge with USDC pricing on Base, pays, receives the response.
Payment settles on-chain after a successful tool result.

## Connect

MCP endpoint:
  https://flashpoint.ai/mcp

For Claude Code, Cursor, or any MCP client:
  $ claude mcp add --transport http flashpoint https://flashpoint.ai/mcp

Autonomous agents authenticate via wallet signature (EIP-191).
See https://docs.flashpoint.ai/authentication for the wallet challenge flow.

## Tools

| Tool                    | What                                                              | USDC    |
|-------------------------|-------------------------------------------------------------------|---------|
| `chat`                  | Multi-step orchestrator — plans, picks tools, runs them, narrates | 0.01    |
| `demographics`          | Population stats for any location — US Census + international     | 0.05    |
| `panel`                 | Multi-action sample tool (see action table below)                 | dynamic |
| `presentation`          | Native `.pptx` deck with editable charts                          | 0.25    |
| `tool_survey`           | Single entry point for surveys — build, edit, launch, recruit (Prolific/Dynata), analyze, export | 0.50    |
| `payment_confirmation`  | Settle an x402-paywalled panel payment intent — wallet-only       | dynamic |

Deprecated aliases still served for one release (don't use in new code):
`get_demographics`, `create_panel`, `surveys_agent`.

### `panel` actions

`panel(action="…")` covers everything sample-related. Pick the action
explicitly — the price is per-action.

| `action`         | What                                                            | USDC |
|------------------|-----------------------------------------------------------------|------|
| `create`         | Build a synthetic panel of AI personas                          | 0.50 |
| `run`            | Run an existing synth panel through a survey                    | 0.10 |
| `create_and_run` | Build a fresh synth panel and run it through a survey in one call (heartbeat-streamed for long runs) | 0.60 |
| `recruit`        | Real PAID respondents from Prolific/Dynata via the surveys agent quote→confirm→checkout flow | 0.50 |

End-to-end synthetic survey from cold:
`tool_survey` (build) → `panel(action="create_and_run")` (build sample + take survey).
Or hand the brief to `chat` and let the orchestrator plan.

For real panel recruitment (Prolific, Dynata) via x402:
1. Call `tool_survey` to author the survey.
2. Call `panel(action="recruit", survey_id=…, provider="prolific")`. The
   agent quotes, asks for confirmation, then returns an
   `x402_payment_required` envelope with an `intent_id`.
3. Call `payment_confirmation(intent_id=…)`. That tool is x402-paywalled
   by the intent's exact marked-up amount. Sign, retry, settle. The
   panel launches automatically when the on-chain settlement clears.

Full tool reference: https://docs.flashpoint.ai/api-reference

## Example: demographics

Request without payment:

```
POST https://flashpoint.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "demographics",
    "arguments": { "location": "94110" }
  }
}
```

Returns `402 Payment Required` with x402 accepts payload:

```json
{
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x4Acb1a8763F3C86Af821fbd37031Ca36d11FEE2F",
    "maxAmountRequired": "50000",
    "resource": "https://flashpoint.ai/mcp",
    "description": "Flashpoint MCP tool: demographics"
  }]
}
```

`maxAmountRequired` is in USDC base units (6 decimals) — `50000` = $0.05.

Sign a `transferWithAuthorization` for that USDC amount, encode it as the
`X-PAYMENT` header, retry the request. You receive age / race / gender /
income / education distributions for the location with AI-powered insights,
and the on-chain transfer settles after the response is delivered.

## Example: paid Prolific panel via x402

Two-stage flow. First, ask the surveys-agent path to quote and prepare
payment. Two MCP round-trips are typical (quote + explicit confirm) to
avoid charging on a stale ask:

```
POST https://flashpoint.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "panel",
    "arguments": {
      "action": "recruit",
      "provider": "prolific",
      "survey_id": "<survey-uuid>",
      "num_respondents": 5
    }
  }
}
```

The agent settles its $0.50 fee, then runs its quote → confirm flow over
the same `conversation_id`. A follow-up call with the returned
`conversation_id` and `"confirm"` in `request` produces the
`x402_payment_required` envelope:

```json
{
  "x402_payment_required": {
    "intent_id": "<uuid>",
    "amount_total_cents": 590,
    "currency": "usd",
    "confirm_tool": "payment_confirmation"
  }
}
```

Then call `payment_confirmation` to settle on chain:

```
POST https://flashpoint.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "payment_confirmation",
    "arguments": { "intent_id": "<uuid-from-envelope>" }
  }
}
```

This returns a 402 with `maxAmountRequired` set to the intent's exact
marked-up amount (e.g. `5900000` = $5.90 for the quote above). Sign,
retry, settle. The Prolific panel launches automatically when the
facilitator's settle confirms.

## Contact

info@flashpoint.ai