API Access and Plans

Public Access

The Philidor API is public for evaluation, research, and development. Anonymous requests receive 10 requests per 60 seconds per IP address. Headline risk scores and tiers are public and stay public: /v1/vaults, per-vault detail, /v1/rwa, per-asset detail, stats, events, protocols, curators, and methodology all answer without a key.

First-party Philidor applications use a separate first-party budget of 60 requests per 60 seconds, so normal product traffic does not consume the anonymous public integration budget.

Keyless access is metered to discourage bulk scraping. Today, list responses cap page size at 100 rows and deep pagination beyond 2000 rows requires a key; from 2026-08-11 those caps tighten to 25 rows and 200 rows. A per-IP daily volume cap applies throughout. Any API key removes these caps.

curl https://api.philidor.io/v1/vaults?limit=5

Endpoints That Require a Plan

The analytical and operational endpoints below require a Data-plan key from 2026-08-11. Until then, anonymous responses keep serving and carry RFC 8594 Sunset, Deprecation, and Warning headers announcing the cutover.

• /v1/stats/history
• /v1/stats/rating-dynamics (rating migration ledger)
• /v1/baskets/* (constituents, weights, versions, rebalance diffs)
• /v1/oracle-vector/*
• /v1/assets/enriched and /v1/assets/enriched/facets
• /v1/vaults/scores (bulk score enumeration)
• /v1/vaults/changes (incremental polling feed)
• /v1/events/stream (live SSE feed)
• /v1/vault/{network}/{address}/holders and /holders/history
• /v1/vault/{network}/{address}/markets, /strategies, /strategy

Also from 2026-08-11, the per-asset detail endpoints (/v1/assets/{chain_id}/{address} and /v1/rwa/{asset_id}) keep answering anonymously with the published score and tier, but the per-dimension values, risk_score_breakdown, and the attestation ledger require a key. Stripped responses name what was withheld in a restricted_fields array.

Limited-release Risk Graph endpoints additionally require an eligible Decisioning key. Public decision verification remains available when the Risk Graph API is enabled.

API Keys

API keys are issued on request and are not self-serve. They use the pk_live_ format and are sent with the Authorization header.

curl -H "Authorization: Bearer pk_live_your_key_here" \
  https://api.philidor.io/v1/vaults?limit=100

Keys are bcrypt-hashed at rest. Each key has its own tier, per-key rate limit, and usage counter.

To request access, use the contact form.

First Call With an Issued Key

After receiving a key, make a small request and confirm that rate-limit headers are present.

curl -i \
  -H "Authorization: Bearer pk_live_your_key_here" \
  "https://api.philidor.io/v1/vaults?limit=1"

Look for HTTP/2 200, X-RateLimit-Limit, X-RateLimit-Remaining, and a JSON body with data.

Plans

Decisioning capabilities are available by arrangement while the Risk Graph API is in limited release.

Keys are provisioned as data, decisioning, or embedded. Decisioning and embedded keys unlock Decisioning capabilities when enabled for the customer arrangement.

Support channels and service commitments are defined in each agreement. Embedded agreements can include uptime and support commitments.

Rate Limit Headers

Responses include rate limit information.

Anonymous Limits By Path

401 and 403 Troubleshooting

Fail-Safe Responses

Risk endpoints can return 503 when the platform is in fail_closed mode. These responses include Retry-After and X-Philidor-FailSafe-Mode.

Baskets Caching

Current basket routes return an ETag and use s-maxage=60 with stale-while-revalidate. Immutable version routes use Cache-Control: public, max-age=31536000, immutable.

If-None-Match returns 304 when the supplied ETag still matches.

Events Stream

GET /v1/events/stream returns text/event-stream. From 2026-08-11 it requires a Data-plan key; until then anonymous connections keep working and carry the Sunset notice headers. The stream sends heartbeat comments every 20 seconds and allows up to 5 concurrent connections per IP.

Browser EventSource cannot send an Authorization header, so browser consumers should connect through a server-side relay that holds the key. Server-side consumers pass the key on the underlying request:

// Node 20+ with the `eventsource` package (v3):
import { EventSource } from 'eventsource';

const source = new EventSource('https://api.philidor.io/v1/events/stream', {
  fetch: (input, init) =>
    fetch(input, {
      ...init,
      headers: { ...(init?.headers ?? {}), Authorization: 'Bearer pk_live_your_key_here' },
    }),
});
source.addEventListener('published', (event) => {
  console.log(JSON.parse(event.data));
});

Event frames use published, promoted, or retracted.

Basket Webhooks

Basket webhook CRUD is available to decisioning and embedded keys.

Outbound deliveries include X-Philidor-Signature in this format.

t=<unix_ts>,v1=<hex>

Philidor signs the string timestamp.body with HMAC-SHA-256. Receivers should enforce a five-minute tolerance. Multiple v1 segments are accepted to support secret rotation. The signing secret is shown only at creation.