The DFRDS API

Send the key as a bearer token. Each key carries the scopes it was minted with and, optionally, the addresses it may be used from. A request outside either is a 403 whose error names the rule: missing_scope or ip_not_allowed.

curl -H "Authorization: Bearer dfk_your_key" \
  "https://dfrds.com/api/v1/me"

A key minted on sandbox.dfrds.com works only there, against sandbox data. Production keys are separate; nothing is shared between the two.

Every list pages by cursor. A page carries next_cursor (null on the last page) and a Link: <…>; rel="next" header with the same request and the next cursor filled in. Pass it back as cursor. The cursor is opaque and stays valid while rows are appended above it, which an offset would not. Page size is limit, default 50, never more than 500 rows: a larger slice is an export.

GET /api/v1/liquidations?protocol=aave_v3&collateral=WETH&limit=200

{
  "protocol": "aave_v3",
  "matching": 1834,
  "count": 200,
  "next_cursor": "WzIxMzQ1Njc4LDEyXQ",
  "limit": 200,
  "max_rows": 500,
  "liquidations": [ … ]
}

The REST limit is per key, per clock hour, from your plan (api_requests_per_hour). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; the 429 says when the window resets. The counter is a row per key per window, so it survives a deploy, a restart and a cache flush. MCP has its own daily budget (mcp_calls_per_day) so an agent session cannot spend a script's hour.

The version is in the path (/api/v1). Fields are added without a version change; a field is never removed or renamed inside a version. When an endpoint is retired it answers for at least six months with two headers first: Deprecation (when it was deprecated) and Sunset (the date it stops), plus a Link: rel="successor-version" to what replaces it. Nothing is deprecated today. Watch for those headers in your client and you will never be surprised.

An API key belongs to an organization; research belongs to a space. A key reaches the spaces its organization’s members belong to, and no wider. It grants no access the organization doesn’t already have. Exports and derived citations are made as the member who minted the key: the monthly export quota is theirs and the citation lands in their research space.

Each cited value on a page carries verification_state: verified, mismatch or unresolved. A consumer can tell a figure that still holds from one that has drifted since it was written. Treat mismatch as a finding, not a formatting detail.

Register an https endpoint on your organization page to be pushed events instead of polling. Every delivery is signed: X-DFRDS-Event names the event and X-DFRDS-Signature is the HMAC-SHA256 of the raw body, hex encoded, keyed with your endpoint secret. Sign the raw bytes you received, before any JSON parsing, and compare in constant time.

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

• Events: price_alert.triggered, data_export.ready, liquidation.recorded, chain_event.created.
• A null figure means we could not derive that value. It does not mean zero.
• Reply 2xx within 10 seconds and do the work asynchronously. Deliveries retry with backoff; ten consecutive failures disable the endpoint until you re-enable it.
• A retry can deliver twice. Treat the event as idempotent on its identifiers.