# payflowagent

> Job: which nad.fun tokens on Monad should an agent watch or buy? Decision-ready score, riskLevel, action. Start free at /v1/screen/sample (no token needed). Pay-per-call via x402.

## Endpoints
- GET https://nad.payflowagent.net/v1/screen/sample  Free. Start here if you have no token address: top 3 pre-scored nad.fun tokens (score, riskLevel, action). Free, rate-limited.
- GET https://nad.payflowagent.net/v1/lite  Free. Free score (0-100), riskLevel, action for one token. Requires ?token=0x…
- GET https://nad.payflowagent.net/v1/decide  Paid ($0.10 USDC, x402). Full decision report for one nad.fun token: score, riskLevel, action, factors, graduation, momentum. Free probes: GET /v1/screen/sample or GET /v1/lite?token=0x…
- GET https://nad.payflowagent.net/v1/token/:addr/summary  Paid ($0.03 USDC, x402). Cheap entry: graduation % + momentum for one token. Free probes: GET /v1/screen/sample or GET /v1/lite?token=0x…
- GET https://nad.payflowagent.net/v1/screen  Paid ($0.05 USDC, x402). Poll-friendly ranked list of fresh nad.fun tokens (score, riskLevel, action, graduation, holders). Free mini-list: GET /v1/screen/sample
- POST https://nad.payflowagent.net/v1/batch/decide  Paid ($0.50 USDC, x402). Full decide reports for up to 10 nad.fun tokens in ONE paid call (package price). Body: {"tokens": ["0x...", ...]}. Cheaper than 10x decide (10x $0.10 = $1.00 vs $0.50). Free probes: GET /v1/screen/sample or GET /v1/lite?token=0x…

## How to pay (x402)
An HTTP 402 is NOT an error: it means the endpoint requires a micro-payment in USDC.
Any x402-capable client (x402-fetch, @x402/core, this suite's MCP server) pays automatically.
Without a client: settle the payment request from the PAYMENT-REQUIRED header / response body, then retry the same request with the signed X-PAYMENT header.

### Minimal JS example (works for every paid endpoint)
```js
import { privateKeyToAccount } from "viem/accounts";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

// Dedizierte Zahler-Wallet mit etwas USDC + ETH (Gas) auf Base - NIE in Code, nur Env!
const key = process.env.X402_BUYER_PRIVATE_KEY;
const core = new x402Client();
registerExactEvmScheme(core, { signer: privateKeyToAccount(key), schemeOptions: { rpcUrl: "https://mainnet.base.org" } });
const http = new x402HTTPClient(core);

async function paidFetch(url, init = {}) {
  const r1 = await fetch(url, { ...init, headers: { accept: "application/json", ...(init.headers || {}) } });
  if (r1.status !== 402) return r1; // 200/4xx -> kein Bezahlfall
  const body = await r1.json();
  const required = http.getPaymentRequiredResponse((n) => r1.headers.get(n), body);
  const payload = await http.createPaymentPayload(required);
  const payHeaders = http.encodePaymentSignatureHeader(payload);
  return fetch(url, { ...init, headers: { accept: "application/json", ...payHeaders } });
}

// Beispiel: bezahlter Decide-Call (nad.fun, $0.10)
const res = await paidFetch("https://nad.payflowagent.net/v1/decide?token=0x...");
const decision = await res.json(); // score, riskLevel, action, factors
```

Setup: `npm i @x402/core @x402/evm viem` and set `X402_BUYER_PRIVATE_KEY` to a dedicated wallet funded with a little USDC + ETH (gas) on Base.
Never hardcode keys; use the environment variable.

### Easiest: use the MCP server (no own x402 code needed)
- `npx -y payflowagent-mcp` pays automatically for every tool.
- Reference polling bot: `examples/screen-bot` in this repo (paid /v1/screen, Discord/Slack webhook).
- Network: eip155:8453 · Asset: USDC · Scheme: exact · Pay to: 0x617122b245C776A6B83A1f2821617819E2d38F6b

## Machine-readable
- OpenAPI: https://nad.payflowagent.net/openapi.json
- x402 manifest: https://nad.payflowagent.net/.well-known/x402.json

## PayFlowAgent suite
- Full product catalog: https://payflowagent.net/catalog.json
- Sibling APIs: nad.payflowagent.net (token intel), data.payflowagent.net (DeFi), enrich.payflowagent.net (web search/scrape), trust.payflowagent.net (Base wallet risk)
- MCP (Cursor/Claude): npx -y payflowagent-mcp

## Updates
- Bluesky: https://bsky.app/profile/payflowagent.bsky.social
- Telegram: https://t.me/payflowagent

## Start here (no token address)
- GET https://nad.payflowagent.net/v1/screen/sample
- Then GET https://nad.payflowagent.net/v1/lite?token=<token from sample>
- Demo token: 0x9cF1538f92341A311a922D411DE8C471DCEA7777

## What you get
- score (0-100), riskLevel, action
- graduation progress (bonding-curve %), 5-minute momentum
- explainable factors (full report only)

## Who pays for this
- Trading / screener agents on Monad that need decide-ready risk signals
- Bots that poll /v1/screen for fresh ranked tokens

## Batch (cheapest per token)
- POST https://nad.payflowagent.net/v1/batch/decide  Body: {"tokens": ["0x...", ...]}  (1-10 tokens, one x402 payment)
- Returns ok:true reports or ok:false/per-token errors — no need to request each token separately.

## Notes
- Prefer /v1/screen/sample when you do not already have a token address.
- Token addresses are nad.fun tokens on Monad (mainnet, 0x..., 42 hex chars).