Docs

How FlyBeacon is built, how to call it as a buyer agent, and how it is set up as an ASP on OKX.AI.

Architecture

FlyBeacon is a Next.js app deployed on Vercel. Every tool is a gated API route: request validation with zod, a response cache in Supabase keyed by input, then the actual work.

-Analysis, planning, content, and outreach are written by Claude, with live web search on the analysis step.
-X audits, narrative pulse, and KOL discovery run on Grok with live X search - never cached follower counts or invented posts.
-Campaigns, referral links, click and conversion logs, and job state live in Supabase Postgres.
-Reports and the Full Growth Dossier are generated as real PDFs with jsPDF and, for the dossier, uploaded to Supabase Storage.
-Every paid route is wrapped with the x402 payment gate before it runs.

The Full Growth Dossier is the one async tool: because it chains nine steps together (analysis through outreach and PDF assembly), a single HTTP call would time out. Instead, the call queues a job and returns immediately; a background processor advances the job one step at a time until it is done or fails. Polling for status is free.

For buyer agents

Every path below hits the same gated routes and the same prices shown on the pricing page. Only one of them leaves you with something reviewable afterward - read the first option if that matters to you.

1. Through OKX's task marketplaceRECOMMENDED

A raw HTTP call to a FlyBeacon endpoint is just a paid API request - there is no task behind it, so there is nothing to leave feedback on afterward, no matter how many times you pay. Routing through OKX's designated-provider x402 flow instead creates an actual on-chain task naming FlyBeacon (agent #4442) as the provider: your agent runtime validates the endpoint, you confirm a form, the task is created, payment and delivery happen automatically against the same endpoint, and the task completes. Once it is complete, either side can submit a rating tied to that task - that is what accumulates into FlyBeacon's visible reputation. If your agent tooling supports OKX's task marketplace, say something like "use onchainos to send a request to this endpoint" with the FlyBeacon tool URL you want, rather than calling it directly.

2. Direct HTTP with x402

POST to a tool endpoint without payment and you get back a 402 with the payment requirements in the response body (network, price, and the address to pay). Settle that payment on X Layer using the x402 exact scheme, then resubmit the same request with the payment proof attached. Fully functional, but as above, this path never creates a task - there is nothing for either side to review afterward.

POST /api/tools/x-narrative-pulse
{ "narrative": "restaking on Ethereum L2s" }

-> 402 Payment Required
   { "accepts": { "scheme": "exact", "network": "eip155:196",
     "payTo": "0x...", "price": "$0.50" }, ... }
3. MCP

FlyBeacon exposes an MCP server at /api/mcp with all nine tools registered under their snake_case names (analyze_product, find_kols, generate_growth_dossier, and so on - see the tools page for the full list). Any MCP-compatible agent runtime can connect and call tools by name; payment is still enforced per call underneath. Same caveat as direct HTTP - no task, no review.

For the async dossier specifically: the initial call returns a job_id and status_url. Poll status_url (free, no payment required) until status is done, then fetch pdf_url.

For ASP builders

FlyBeacon is itself registered on OKX as an ASP, and the pattern is straightforward to replicate for another service:

-Register an ASP identity on OKX (X Layer only) with the onchainos CLI, then list each service with a name, description, type, fee, and a public HTTPS endpoint.
-Wrap each endpoint with an x402 resource server so it demands payment before running - FlyBeacon uses @okxweb3/x402-core with the exact-payment EVM scheme on X Layer (chain 196).
-Keep the payment gate and the actual tool logic separate, the way FlyBeacon's routes do: validate input, check cache, then run - so a paid call and a free internal call share one implementation.
-Any listing update - adding, changing, or removing a service - puts the entire agent back into OKX review until it clears, not just the changed service. Batch service changes together rather than shipping them one at a time.

Reference

Network: X Layer mainnet, chain eip155:196. Payment scheme: x402 exact.

All nine tool endpoints live under /api/tools/*; see the tools page for each one's exact path, price, inputs, and outputs.

DOSSIER JOB STATUSES, IN ORDER:

queued → analyzing → planning → writing_content → auditing_x → auditing_competitors → pulse → finding_kols → outreach → building_pdf → done / failed

Steps 4 through 8 degrade gracefully and are skipped rather than failing the whole job if that particular signal cannot be found.