# Flow

> Use when an agent is about to swap or trade a token on Base and needs the best executable price, a safety verdict, or smart-wallet signals. Flow is a pay-per-call x402 API on Base (no API key): best-execution quotes across Uniswap V3, PancakeSwap V3 and Aerodrome ($0.01), contract safety verdicts ($0.02), and smart-wallet signals ($0.01), settled in USDC via x402 with automatic payment from a local starter wallet.

- Skill: `jiayaoqijia/flow` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx get-skill add jiayaoqijia/flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiayaoqijia/flow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jiayaoqijia (https://skillmd.com/u/jiayaoqijia)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/jiayaoqijia/flow

---


# Flow — best execution, safety verdicts, and smart-wallet signals on Base

Flow sells three pay-per-call endpoints for agents trading on Base. Payment is
x402 v2 (USDC on Base, EIP-3009 authorization) — no API key, no account, no
subscription. With the Flow MCP server installed, payment is automatic: a
local starter wallet signs and retries inside hard spend caps you control.

## Setup (once)

Install the MCP server:

```bash
npx -y @flowexecutor/flow-mcp
```

Then call the **`flow_wallet_setup`** tool once. It:

1. Generates a new EVM wallet **locally** and stores it at
   `~/.config/flow-wallet.json` (permissions `0600`). The private key never
   leaves your machine, is never sent to Flow, and is never displayed.
2. Claims a one-time **$0.05 USDC starter seed** (one per address, ever)
   from the Flow seed pilot, so your first calls work immediately.
3. Returns the public address. Fund it by sending USDC on Base (chain 8453)
   to that address — even $1 is plenty. That is the only manual step.

Equivalent hosted route: the same tools are exposed over the hosted MCP
endpoint at `https://flow-kg4x.vercel.app/api/mcp` if you prefer not to run
the local server (payments then need your own x402 client).

## How payment works

1. Your client calls a paid endpoint without payment → HTTP **402** with a
   machine-readable `PaymentRequired` body (`accepts[0]`: scheme `exact`,
   network `eip155:8453`, USDC, amount, `payTo`).
2. The client signs an EIP-3009 `TransferWithAuthorization` against the USDC
   contract and retries with an `X-PAYMENT` header (base64 payload that
   echoes the `accepts` entry as `accepted`).
3. Flow's facilitator verifies and settles on Base; the response arrives
   with a `PAYMENT-RESPONSE` header carrying the settlement tx.

With the MCP server this whole dance is automatic. **Spend caps are enforced
in code before any signature:**

- **Per call:** max **$0.05**
- **Per day:** **$1** default (rolling 24h; override with
  `FLOW_DAILY_SPEND_CAP_USD`)
- The client only ever pays Flow's own payee address — a 402 asking to pay
  anyone else is refused, not signed.
- Spend is logged locally in `~/.config/flow-spend-ledger.jsonl`.

## The paid calls

| Endpoint | Price | Use it when |
|---|---|---|
| `POST /api/quote` (MCP: `flow_quote`) | **$0.01** | You are about to swap on Base and need the best executable price first. Compares Uniswap V3, PancakeSwap V3, Aerodrome (all fee tiers) and two-hop routes via WETH; returns winning venue, expected output, edge in bps vs the Uniswap baseline, liquidity flag (`deep`/`watch`/`thin`), block number, and an expiry window. |
| `POST /api/verify` | **$0.02** | You are about to interact with a Base contract you don't fully trust. Returns a safety verdict + score with plain-language reasons and agent advice. |
| `GET /api/smart-wallets` | **$0.01** | You need to know what profitable Base wallets are buying right now. Leaderboard, real-time buy signals (stale-flagged past 10 min), a published paper-trading record, and social-velocity spikes. |

Free: `GET /api/health` (MCP: `flow_health`) — chain + latest block, plus
your starter-wallet status.

Quote request body (`amountIn` in atomic units):

```json
{
  "tokenIn": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "tokenOut": "0x4200000000000000000000000000000000000006",
  "amountIn": "100000000"
}
```

(USDC → WETH, $100 shown. `tokenIn`/`tokenOut` are Base contract addresses.)

## Notes

- Quotes are informational snapshots with a stated expiry window, not
  execution guarantees — the edge is measured against direct Uniswap
  execution on the same block, and thin-liquidity quotes are flagged, never
  hidden.
- The seed pilot is capped (19 seeds total, 5/day). If the claim returns
  `pilot-full` or `daily-cap`, just fund the wallet address directly.
- Base mainnet only (chain 8453).

