beacons.fyi API Docs

Introduction

beacons.fyi is a reputation and quality oracle for AI services. Given any paid API or MCP endpoint, beacons.fyi returns a verifiable trust score backed by synthetic accuracy probing, opt-in transaction telemetry, and a staked verifier network. Your agent gets a ground-truth answer to is this service any good, and will it rip me off? — before it commits funds.

Scores are identity-anchored (bound to a non-spoofable AP2 DID so reputation cannot be reset), verifiable (every snapshot is attested on-chain by an EigenLayer AVS), and cross-marketplace (neutral infrastructure, not owned by any single platform).

The core mental model: a GET /v1/score before the x402 POST. Pair it with conditional escrow and payment only releases if the result passes your declared criteria — no trusted intermediary required.

Quickstart

Get your API key from the dashboard and make your first score query in under a minute. Free-tier keys are issued immediately — no credit card required.

1 — Obtain an API key

Sign up at beacon.hq/dashboard. Live keys start with bsn_live_; sandbox keys with bsn_test_. Pass the key in every request as a Bearer token.

2 — Query a score

# URL-encode the endpoint path component
curl https://api.beacon.hq/v1/score/api.weather-ai.com%2Fv1%2Fforecast \
  -H 'Authorization: Bearer bsn_live_…'

// Works in Node 18+, Deno, Bun, and modern browsers
const endpoint = encodeURIComponent('api.weather-ai.com/v1/forecast')

const res = await fetch(`https://api.beacon.hq/v1/score/${endpoint}`, {
  headers: {
    'Authorization': `Bearer ${process.env.BEACON_API_KEY}`,
  },
})
const score = await res.json()

// Route only if the score clears your gate
if (score.trust_score < 70 || score.scam_flag) throw new Error('Endpoint does not meet trust threshold')

3 — Inspect the response

{
"endpoint":"api.weather-ai.com/v1/forecast",
"trust_score":87,
"grade":"A",
"accuracy":0.94,
"uptime_pct":99.72,
"latency_p95_ms":143,
"dispute_rate":0.002,
"scam_flag":false,
"sample_size":142830,
"confidence":0.98,
"identity":"did:ap2:0x4f3b…",
"last_updated":"2025-06-28T14:22:01Z",
"attestation_ref":"0xabc123…"
}

Authentication

All beacons.fyi API requests must be authenticated using an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer bsn_live_••••••••••••••••

Never expose a live key in client-side JavaScript. Use environment variables (BEACON_API_KEY) and proxy requests through your backend.

Error codes

The Score Object

Every endpoint that returns score data uses the same canonical object. Fields are always present unless noted as optional.

Full example object

{
"endpoint":"api.weather-ai.com/v1/forecast",
"trust_score":87,
"grade":"A",
"accuracy":0.94,
"uptime_pct":99.72,
"latency_p95_ms":143,
"dispute_rate":0.002,
"scam_flag":false,
"sample_size":142830,
"confidence":0.98,
"identity":"did:ap2:0x4f3b8a…",
"last_updated":"2025-06-28T14:22:01Z",
"attestation_ref":"0xabc123def456…"
}

All requests go to https://api.beacon.hq. Every request requires an Authorization: Bearer <key> header. Responses are application/json.

GET/v1/score/{endpoint_id}

Returns the current trust score for a single endpoint. The endpoint_id must be the URL-encoded hostname + path of the target service.

Path parameters

Query parameters

curl 'https://api.beacon.hq/v1/score/api.llm-router.com%2Fv1%2Fchat?fresh=true&fields=trust_score,scam_flag' \
  -H 'Authorization: Bearer bsn_live_…'

POST/v1/score/batch

Score multiple endpoints in a single round-trip. POST a list of endpoint IDs and receive results ranked by trust_score descending — designed for agent routing loops that need to select the best available service from a candidate set. Maximum 50 IDs per request. Requires Pro or Enterprise.

Request body

curl https://api.beacon.hq/v1/score/batch \
  -X POST \
  -H 'Authorization: Bearer bsn_live_…' \
  -H 'Content-Type: application/json' \
  -d '{ "ids": ["svc-a.com", "svc-b.com", "svc-c.com"], "min_score": 70 }'

{
"best":"svc-b.com",
"count":3,
"ranked":[…array of Score Objects, sorted by trust_score desc…]
}

POST/v1/receipt

Submit a signed transaction receipt to contribute telemetry to beacons.fyi's scoring pipeline. Receipts feed directly into accuracy and dispute-rate calculations. The signature must be produced by the payer's AP2 identity key so Beacon can bind the data point to a non-spoofable identity.

Request body

curl https://api.beacon.hq/v1/receipt \
  -X POST \
  -H 'Authorization: Bearer bsn_live_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "endpoint_id": "api.weather-ai.com/v1/forecast",
    "outcome": "success",
    "latency_ms": 182,
    "amount": 0.002,
    "disputed": false,
    "signature": "base64EncodedSig…"
  }'

{
"receipt_id":"rcpt_01j9zb…",
"status":"accepted",
"queued_at":"2025-06-28T14:25:11Z"
}

GET/v1/attestation/{id}

Retrieve the full on-chain attestation backing a score. Each score snapshot is attested by beacons.fyi's EigenLayer AVS and posted to the Ethereum Attestation Service (EAS). Use attestation_ref from any Score Object as the id path parameter. Any party can independently verify the score without trusting beacons.fyi's API.

{
"id":"0xabc123def456…",
"endpoint_id":"api.weather-ai.com/v1/forecast",
"trust_score":87,
"attested_at":"2025-06-28T14:22:01Z",
"attester":"beacon-avs-v2",
"chain":"ethereum",
"eas_uid":"0xdef456…",
"avs_operator":"0x7f3a…",
"explorer_url":"https://easscan.org/attestation/view/0xdef456…"
}

Conditional Escrow

beacons.fyi's optional escrow module lets a payer agent lock funds before calling an endpoint, then release or refund them atomically once beacons.fyi's verifiers attest the result against declared criteria — without a trusted intermediary. Available on Enterprise plans.

// 1 — Check score before opening escrow
const score = await beacon.score('api.weather-ai.com/v1/forecast')

// 2 — Open escrow with structured criteria
const escrow = await beacon.escrow.open({
  endpoint: 'api.weather-ai.com/v1/forecast',
  amount: 0.05,
  criteria: {
    trust_score: { gte: 80 },
    scam_flag: false,
  },
})

// 3 — Settlement is automatic; poll or use webhook
console.log(escrow.id, escrow.status)  // "pending_attestation"

Rate Limits & Pricing

Rate limits

Rate-limit headers on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp). A 429 includes Retry-After.

Plans

Reads are free to start so your agents can query beacons.fyi everywhere. You pay as volume and verification needs grow. Pro includes 100k reads/mo; additional queries at $0.001 / query.

SDKs

First-party SDKs handle authentication, retries, pagination, and response typing. All are open-source, MIT-licensed, and published to their respective package registries.

The TypeScript SDK ships full type definitions for all request and response objects. The Python SDK supports both sync and async/await usage. The Go SDK is idiomatic Go with context support and automatic retries.