API Reference

Programmatic access to SEC EDGAR crypto ETF filing data, issuer profiles, regulatory review history, and pipeline intelligence.

Base URL: https://api.cryptoetfsentinel.com

For interactive testing, try the Swagger UI.

Disclaimer: Data provided through this API is for informational purposes only and does not constitute investment advice. Outcome signals and risk scores are heuristic estimates based on historical filing patterns — not predictions or probabilities. See our full Data Disclaimer.

Quick Start

1. Try a free endpoint — no API key needed:

curl https://api.cryptoetfsentinel.com/v1/currencies

2. Search filings with natural language:

curl "https://api.cryptoetfsentinel.com/v1/filings/search?q=bitcoin+spot+ETF"

3. Unlock paid features — subscribe, then add your API key:

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/issuers

4. Or pay per call as an AI agent — no subscription, no API key. Send a request with no X-Api-Key header and you receive an x402 payment challenge (USDC on Base or Solana) that an x402 client settles automatically. See x402 Payments.

Authentication

Pass your API key in the X-Api-Key header. Requests without a key receive free-tier access.

curl

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/issuers

Python

import requests

resp = requests.get(
    "https://api.cryptoetfsentinel.com/v1/issuers",
    headers={"X-Api-Key": "sk_live_YOUR_KEY"}
)
print(resp.json())

JavaScript

const resp = await fetch(
  "https://api.cryptoetfsentinel.com/v1/issuers",
  { headers: { "X-Api-Key": "sk_live_YOUR_KEY" } }
);
const data = await resp.json();
console.log(data);

Tiers

Feature	Free	Developer ($10/mo)	Professional ($25/mo)
Filing history (3,000+)	All	All	All
Semantic search	Unlimited	Unlimited	Unlimited
Currencies & form types	All	All	All
Aggregate stats	Full	Full	Full
API calls	25 / day (429 when exhausted; resets 00:00 UTC — x402 payment challenges don't count)	Unlimited daily	Unlimited daily
Data freshness	24-hour delay	Real-time	Real-time
ETF profiles & comparison	--	Full access	Full access
Issuers list	All 103 — stage preview (24h delay)	All 103, full fields	All 103, full fields
Activity feed & events	--	Full access	Full access
Regulatory Review Profile	--	Full access	Full access
Comment letter history	--	Full history	Full history
Query Intelligence (parse, aggregate)	Full access	Full access	Full access
ETF Financials (AUM, NAV, expenses)	--	Full access	Full access
ETF Profiles (custodian, fees, APs)	--	Single issuer	All + history
ETF Comparison (side-by-side)	--	Full access	Full access
Pipeline Intelligence (risk, outcome signals, velocity)	--	--	Full access
Terminal Dashboard	--	--	Full access

Get a key by subscribing on the pricing page: Developer $10/mo, Professional $25/mo.

Discovery Endpoints

FREE No API key required. Rate limit: 300 requests/minute.

GET /v1/currencies

List all tracked cryptocurrencies with their filing counts.

Response

{
  "data": [
    { "currency": "bitcoin", "count": 892 },
    { "currency": "ethereum", "count": 456 },
    { "currency": "solana", "count": 127 }
  ],
  "meta": { "total": 29 },
  "error": null
}

GET /v1/form-types

List all SEC form types present in the database with counts.

Response

{
  "data": [
    { "filing_type": "S-1", "count": 245 },
    { "filing_type": "19b-4", "count": 189 },
    { "filing_type": "EFFECT", "count": 88 }
  ],
  "meta": { "total": 42 },
  "error": null
}

GET /v1/stats

Aggregate statistics: total filings, date range, breakdowns by currency and form type.

Response

{
  "data": {
    "total_filings": 2580,
    "earliest_filing": "2013-07-01",
    "latest_filing": "2026-03-07",
    "filings_by_currency": [
      { "currency": "bitcoin", "count": 892 }
    ],
    "filings_by_type": [
      { "filing_type": "S-1", "count": 245 }
    ],
    "known_issuers": 110
  },
  "meta": {},
  "error": null
}

GET /v1/issuers

List all known crypto ETF issuers, sorted alphabetically. Free tier: full universe with name, ticker, crypto, and 24h-delayed pipeline stage (other fields null). Developer+: all fields live, including journey_node and trading_date.

Response

{
  "data": [
    {
      "cik": "0001559992",
      "name": "Grayscale Bitcoin Trust (BTC)",
      "crypto": "bitcoin",
      "currencies": [],
      "ticker": "GBTC",
      "exchange": "NYSE Arca",
      "owner_org": "09 Crypto Assets",
      "sic": "6221",
      "entity_type": "operating",
      "issuer_type": "dedicated"
    }
  ],
  "meta": { "total": 15, "full_count": 110 },
  "error": null
}

meta.full_count shows the true total across all tiers.

Filing Endpoints

FREE No API key required. Rate limit: 100 requests/minute.

GET /v1/filings

Paginated list of filings with powerful filtering.

Query Parameters

Name	Type	Default	Description
`currency`	string	--	Filter by cryptocurrency (e.g. `bitcoin`, `ethereum`)
`filing_type`	string	--	Filter by SEC form type (e.g. `S-1`, `19b-4`)
`company`	string	--	Substring match on company name
`date_after`	string	--	ISO date (YYYY-MM-DD), filings after this date
`date_before`	string	--	ISO date (YYYY-MM-DD), filings before this date
`title_contains`	string	--	Substring match on filing title
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Skip this many results
`order_by`	string	published_desc	Sort order: `published_desc`, `published_asc`, `company_asc`, `company_desc`

Example

curl "https://api.cryptoetfsentinel.com/v1/filings?currency=bitcoin&filing_type=S-1&limit=5"

Response

{
  "data": [
    {
      "link": "https://www.sec.gov/Archives/edgar/data/...",
      "title": "Registration Statement",
      "company": "Grayscale Bitcoin Trust (BTC)",
      "filing_type": "S-1",
      "changes": "Filed",
      "published": "2026-03-05",
      "keywords": ["bitcoin", "etf"],
      "source": "SEC",
      "currency": "bitcoin",
      "currencies": [],
      "primary_doc": "0001193125-26-061537.txt",
      "accession": "0001193125-26-061537",
      "sec_url": "https://www.sec.gov/cgi-bin/browse-edgar?action=..."
    }
  ],
  "meta": { "total": 245, "limit": 5, "offset": 0, "page": 1 },
  "error": null
}

GET /v1/filings/{accession}

Retrieve a single filing by accession number with metadata, currency classification, and direct EDGAR link. Accepts dashed (0001193125-26-061537) or undashed format.

Example

curl https://api.cryptoetfsentinel.com/v1/filings/0001193125-26-061537

Search

FREE Semantic search powered by FAISS vector embeddings with keyword fallback. Rate limit: 100 requests/minute.

GET /v1/filings/search

Natural language search across all filings. Uses FAISS cosine similarity when the index is loaded, falling back to keyword matching.

Query Parameters

Name	Type	Default	Description
`q`	string	required	Search query (2-500 characters)
`limit`	integer	10	Max results (1-50)

Example

curl "https://api.cryptoetfsentinel.com/v1/filings/search?q=solana+spot+ETF+approval&limit=5"

Response

{
  "data": {
    "query": "solana spot ETF approval",
    "results": [
      {
        "filing": {
          "link": "https://www.sec.gov/...",
          "title": "EFFECT",
          "company": "Grayscale Solana Trust",
          "filing_type": "EFFECT",
          "currency": "solana",
          "accession": "...",
          "published": "2026-02-15"
        },
        "score": 0.8721
      }
    ],
    "method": "faiss"
  },
  "meta": { "total": 5 },
  "error": null
}

method is faiss for vector search or keyword for text fallback. Returns 503 if the FAISS index is unavailable.

Issuer Endpoints

GET /v1/issuers/{cik}

Detailed issuer profile including regulatory review status, the 5-node journey position (journey_node) and real trading_date, filing count, and registered series. The review_profile field is gated for free-tier users.

Path Parameters

Name	Type	Description
`cik`	string	SEC CIK (bare or zero-padded, e.g. `1559992`)

Response (Developer / Professional)

{
  "data": {
    "cik": "0001559992",
    "name": "Grayscale Bitcoin Trust (BTC)",
    "crypto": "bitcoin",
    "currencies": [],
    "ticker": "GBTC",
    "exchange": "NYSE Arca",
    "owner_org": "09 Crypto Assets",
    "issuer_type": "dedicated",
    "review_profile": {
      "review_status": "approved",
      "review_rounds": 18,
      "first_letter": "2017-01-06",
      "last_letter": "2024-01-10",
      "review_duration_days": 2561,
      "days_since_last_letter": 789,
      "approval_date": "2024-01-10",
      "uploads": 18,
      "correspondences": 15,
      "stage": "trading",
      "listing_date": "2024-01-10",
      "effectiveness_date": "2024-01-10",
      "trading_date": "2024-01-10",
      "completing_signal": "EFFECT",
      "journey_node": "Trading"
    },
    "filing_count": 127,
    "series": [
      {
        "series_id": "S000076502",
        "name": "Grayscale Bitcoin Trust (BTC)",
        "tickers": ["GBTC"],
        "crypto": "bitcoin",
        "product_type": "etf"
      }
    ]
  },
  "meta": {},
  "error": null
}

Regulatory journey fields

journey_node — the issuer's position on the 5-node journey: Registration Filed → Under Review → Launch Imminent → Approved → Trading (null for off-track stages such as withdrawn/delisted).
listing_date / effectiveness_date — the two legs that complete a launch: '34 Act exchange listing (CERT) and '33 Act registration effectiveness (EFFECT/424B). They can land in either order.
trading_date — when the fund actually became tradeable: the later of the two legs. null until both land. Use this (not approval_date) as the "now trading" milestone.
completing_signal — the SEC form type of the leg that landed second (completed trading).

Response (Free Tier)

The review_profile field returns a gated sentinel instead of data:

"review_profile": { "gated": true, "required_tier": "developer" }

GET /v1/issuers/{cik}/filings

All filings for a specific issuer, paginated. FREE

Query Parameters

Name	Type	Default	Description
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Skip this many results

Example

curl https://api.cryptoetfsentinel.com/v1/issuers/1559992/filings?limit=5

Activity Feed

DEVELOPER Real-time filing activity feed. Returns 402 for free-tier requests. Rate limit: 100 requests/minute.

GET /v1/events

Recent filing activity across all tracked issuers. Returns the latest filings with ticker symbols and issuer metadata. Useful for building activity feeds and monitoring new filings in real-time.

Query Parameters

Name	Type	Default	Description
`limit`	integer	20	Results per page (1-50)
`currency`	string	all	Filter by cryptocurrency (e.g. bitcoin, ethereum)

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/events?limit=10

Response

{
  "data": [
    {
      "title": "S-1/A filing",
      "company": "Grayscale Bitcoin Trust",
      "filing_type": "S-1/A",
      "published": "2025-03-20",
      "currency": "bitcoin",
      "ticker": "GBTC",
      "link": "https://www.sec.gov/Archives/edgar/data/..."
    }
  ],
  "meta": { "total": 10 },
  "error": null
}

Comment Letters

DEVELOPER Returns 402 for free-tier requests. Rate limit: 100 requests/minute.

GET /v1/issuers/comment-letters?cik={cik}

SEC comment letter history and regulatory review profile for an issuer. Includes both UPLOAD (SEC to issuer) and CORRESP (issuer to SEC) filings. The cik param is optional — omit it for the largest issuer by AUM (a live sample), or pass a CIK to target a specific issuer.

Response

{
  "data": {
    "review_profile": {
      "review_status": "approved",
      "review_rounds": 18,
      "uploads": 18,
      "correspondences": 15,
      "first_letter": "2017-01-06",
      "last_letter": "2024-01-10",
      "approval_date": "2024-01-10",
      "stage": "trading",
      "trading_date": "2024-01-10",
      "journey_node": "Trading"
    },
    "letters": [
      {
        "accession": "0001193125-24-006237",
        "cik": "0001559992",
        "form_type": "UPLOAD",
        "filing_date": "2024-01-10",
        "file_number": "333-259574",
        "company": "Grayscale Bitcoin Trust (BTC)",
        "crypto_relevant": 1
      }
    ]
  },
  "meta": { "total": 33 },
  "error": null
}

Query Intelligence

FREE Natural-language query parsing and filing aggregation. No API key required.

POST /v1/query/parse

Parse a natural-language question into a structured intent with extracted filters. Lightweight — no database or vector search calls. Useful for building search UIs or routing queries programmatically. Rate limit: 100/min.

Request Body

Field	Type	Description
`q`	string	Natural-language query (e.g. "How many Solana ETF filings are there?")

Example

curl -X POST https://api.cryptoetfsentinel.com/v1/query/parse \
  -H "Content-Type: application/json" \
  -d '{"q": "How many Solana ETF filings are there?"}'

Response

{
  "data": {
    "intent": "count",
    "confidence": 0.95,
    "filters": {
      "currency": "solana",
      "filing_type": null,
      "company": null,
      "date_after": null,
      "date_before": null
    },
    "group_by": null,
    "limit": null,
    "topic": null,
    "education": null
  },
  "meta": { "total": 0 },
  "error": null
}

Intent Types

Intent	Description
`search`	Semantic search across filings (FAISS)
`count`	Numeric count of matching filings
`list`	List matching filings
`aggregate`	Group and count by field
`explain`	Educational explanation of a topic

GET /v1/query/aggregate

Group filings by a field and return value + count pairs, sorted by count descending. Rate limit: 60/min.

Query Parameters

Name	Type	Required	Description
`group_by`	string	Yes	Field to group by: `company`, `filing_type`, `currency`, or `issuer`
`currency`	string	No	Filter by cryptocurrency
`filing_type`	string	No	Filter by SEC form type
`company`	string	No	Filter by company name

Example

curl "https://api.cryptoetfsentinel.com/v1/query/aggregate?group_by=company¤cy=bitcoin"

Response

{
  "data": [
    { "value": "Grayscale Bitcoin Trust (BTC)", "count": 187 },
    { "value": "iShares Bitcoin Trust ETF", "count": 94 },
    { "value": "Bitwise Bitcoin ETF", "count": 62 }
  ],
  "meta": { "total": 28 },
  "error": null
}

ETF Financials

DEVELOPER Structured financial data from SEC filings (10-K, 10-Q). Covers AUM, NAV, expense ratios, sponsor fees, and more for 40+ crypto ETFs. Returns 402 for free-tier requests.

GET /v1/xbrl/leaderboard

Rank crypto ETFs by a financial metric. Default: AUM (assets under management). Uses each issuer's latest reported value.

Query Parameters

Name	Type	Default	Description
`concept`	string	InvestmentOwnedAtFairValue	Financial metric to rank by (see valid concepts below)
`unit`	string	auto	Unit filter (auto-resolved from concept if omitted)
`taxonomy`	string	auto	Taxonomy filter (auto-resolved if omitted)
`limit`	integer	20	Max results (1-50)

Valid Concepts

Concept	Unit	Description
`InvestmentOwnedAtFairValue`	USD	Assets under management (AUM)
`NetAssetValuePerShare`	USD/shares	NAV per share
`SharesOutstanding`	shares	Total shares outstanding
`SponsorFees`	USD	Sponsor/management fees (period)
`InvestmentCompanyExpenseRatioIncludingIncentiveFee`	pure	Expense ratio (decimal)
`StockIssuedDuringPeriodSharesNewIssues`	shares	Shares created (period)
`StockRedeemedOrCalledDuringPeriodShares`	shares	Shares redeemed (period)
`InvestmentCompanyTotalReturn`	pure	Total return (decimal)
`EntityPublicFloat`	USD	Public float (dei taxonomy)

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  "https://api.cryptoetfsentinel.com/v1/xbrl/leaderboard?limit=5"

Response

{
  "data": [
    {
      "cik": "0001980994",
      "company": "iShares Bitcoin Trust ETF",
      "value": 67400000000,
      "period_end": "2025-09-30",
      "fiscal_year": 2025,
      "fiscal_period": "Q3"
    },
    {
      "cik": "0001588489",
      "company": "Grayscale Bitcoin Trust (BTC)",
      "value": 20200000000,
      "period_end": "2025-09-30",
      "fiscal_year": 2025,
      "fiscal_period": "Q3"
    }
  ],
  "meta": {
    "total": 28,
    "concept": "InvestmentOwnedAtFairValue",
    "unit": "USD"
  },
  "error": null
}

GET /v1/xbrl/issuer?cik={cik}

Financial snapshot for a single issuer: latest AUM, NAV per share, shares outstanding, expense ratio, sponsor fees, and total return. The cik param is optional — omit it for the largest issuer by AUM (a live sample), or pass a CIK to target a specific issuer.

Query Parameters

Name	Type	Description
`cik`	string	SEC CIK (bare or zero-padded, e.g. `1588489`)

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  "https://api.cryptoetfsentinel.com/v1/xbrl/issuer?cik=1588489"

Response

{
  "data": {
    "cik": "0001588489",
    "company": "Grayscale Bitcoin Trust (BTC)",
    "period_end": "2025-09-30",
    "aum": 14500000000,
    "nav_per_share": 68.42,
    "shares_outstanding": 211900000,
    "expense_ratio": 0.0152,
    "sponsor_fees": 290500000,
    "total_return": 0.6084,
    "fact_count": 1048
  },
  "meta": {},
  "error": null
}

GET /v1/xbrl/series?cik={cik}

Historical time series for one financial metric. Ideal for charting AUM growth, NAV trends, or expense changes over time. Ordered by period end date ascending. The cik param is optional — omit it for the largest issuer by AUM (a live sample), or pass a CIK to target a specific issuer.

Query Parameters

Name	Type	Default	Description
`cik`	string	optional	SEC CIK; omit for largest issuer by AUM
`concept`	string	InvestmentOwnedAtFairValue	Financial metric (see valid concepts above)
`unit`	string	auto	Unit filter (auto-resolved if omitted)
`taxonomy`	string	auto	Taxonomy filter (auto-resolved if omitted)

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  "https://api.cryptoetfsentinel.com/v1/xbrl/series?cik=1588489&concept=NetAssetValuePerShare"

Response

{
  "data": [
    {
      "period_end": "2024-12-31",
      "value": 42.18,
      "filed_date": "2025-02-28",
      "form_type": "10-K",
      "fiscal_year": 2024,
      "fiscal_period": "FY"
    },
    {
      "period_end": "2025-03-31",
      "value": 55.67,
      "filed_date": "2025-05-15",
      "form_type": "10-Q",
      "fiscal_year": 2025,
      "fiscal_period": "Q1"
    }
  ],
  "meta": {
    "total": 8,
    "concept": "NetAssetValuePerShare",
    "unit": "USD/shares"
  },
  "error": null
}

GET /v1/xbrl/aum-growth

Quarterly aggregate AUM across all crypto ETFs, broken down by cryptocurrency category (Bitcoin, Ethereum, Solana, Multi-crypto, Other). Data sourced from SEC XBRL filings.

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/xbrl/aum-growth

Response

{
  "data": [
    {
      "quarter": "2025-Q3",
      "period_end": "2025-09-30",
      "total_aum": 125400000000,
      "issuer_count": 28,
      "breakdown": {
        "bitcoin": 98200000000,
        "ethereum": 18600000000,
        "solana": 2100000000,
        "multi": 4200000000,
        "other": 2300000000
      }
    }
  ],
  "meta": {
    "total": 6,
    "concept": "InvestmentOwnedAtFairValue",
    "unit": "USD"
  },
  "error": null
}

GET /v1/xbrl/fee-war

Current expense ratio for each crypto ETF, sorted cheapest first. Uses a multi-concept priority fallback to maximise coverage. Includes raw sponsor fees, AUM, and fee waiver expiry dates where applicable.

Query Parameters

Name	Type	Default	Description
`crypto`	string	all	Filter by cryptocurrency (e.g. `bitcoin`, `ethereum`)

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  "https://api.cryptoetfsentinel.com/v1/xbrl/fee-war?crypto=bitcoin"

Response

{
  "data": [
    {
      "cik": "0002044319",
      "company": "Franklin Bitcoin ETF",
      "crypto": "bitcoin",
      "ticker": "EZBC",
      "expense_ratio": 0.0019,
      "expense_ratio_bps": 19.0,
      "period_end": "2025-09-30",
      "sponsor_fees": 1250000,
      "aum": 694000000,
      "fee_waiver_expiry": "2026-08-02"
    }
  ],
  "meta": { "total": 12, "concept": "expense_ratio", "unit": "pure" },
  "error": null
}

GET /v1/xbrl/fee-war/history

Quarterly fee history for all crypto ETFs. Each quarter contains a list of issuers with their expense ratio at that point. Useful for charting the fee war progression over time.

Query Parameters

Name	Type	Default	Description
`crypto`	string	all	Filter by cryptocurrency

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/xbrl/fee-war/history

Response

{
  "data": [
    {
      "quarter": "2025-Q1",
      "period_end": "2025-03-31",
      "issuers": [
        {
          "cik": "0002044319",
          "company": "Franklin Bitcoin ETF",
          "ticker": "EZBC",
          "expense_ratio": 0.0019,
          "expense_ratio_bps": 19.0
        }
      ]
    }
  ],
  "meta": { "total": 4, "concept": "expense_ratio", "unit": "pure" },
  "error": null
}

ETF Profiles

Operational data extracted from POS AM (Post-Effective Amendment) filings. Includes custodian, sponsor fee, reference rate, basket size, authorized participant counts, and in-kind eligibility. Rate limit: 100 requests/minute.

GET /v1/profiles/issuer?cik={cik} DEVELOPER

Current operational profile for a single issuer. Returns the most recent POS AM extraction. The cik param is optional — omit it for the largest issuer by AUM (a live sample), or pass a CIK to target a specific issuer.

Response

{
  "data": {
    "cik": "0002044319",
    "filing_date": "2025-11-04",
    "custodian": "Coinbase Custody Trust Company",
    "sponsor_fee": "0.25%",
    "fee_waiver_expiry": null,
    "reference_rate": "CME CF Bitcoin Reference Rate",
    "basket_size": 4000,
    "inkind_eligible": true,
    "ap_count_cash": 8,
    "ap_count_inkind": 4,
    "fee_delta": null,
    "custodian_changed": false,
    "ap_count_cash_delta": null
  },
  "meta": { "total": 0, "limit": 20, "offset": 0, "page": 1 },
  "error": null
}

GET /v1/profiles/latest PROFESSIONAL

Latest profile per trading issuer. Bulk export of all current ETF operational data.

GET /v1/profiles/history?cik={cik} PROFESSIONAL

Profile evolution timeline for an issuer. Each entry shows what changed vs the prior POS AM filing — fee adjustments, custodian switches, AP roster changes, and in-kind eligibility transitions. The cik param is optional — omit it for the largest issuer by AUM (a live sample), or pass a CIK to target a specific issuer.

Query params

Param	Default	Description
`cik`	optional	SEC CIK; omit for largest issuer by AUM
`limit`	20	Max entries (1–50)

GET /v1/profiles/comparison DEVELOPER

Side-by-side comparison of all trading crypto ETFs. Merges operational profile data (custodian, fees, authorized participants) with XBRL financial data (AUM, NAV, expense ratio), market data (price, volume, returns), and fund health metrics (tracking error, premium/discount, implied NAV). Sorted by AUM descending. Rate limit: 60/min.

Example

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/profiles/comparison

Response

{
  "data": [
    {
      "cik": "0001980994",
      "name": "iShares Bitcoin Trust ETF",
      "ticker": "IBIT",
      "crypto": "bitcoin",
      "exchange": "NASDAQ",
      "custodian": "Coinbase Custody Trust Company",
      "sponsor_fee": "0.25%",
      "basket_size": 4000,
      "inkind_eligible": true,
      "ap_count_cash": 8,
      "aum": 67400000000,
      "nav_per_share": 55.12,
      "expense_ratio": 0.0025,
      "market_price": 55.28,
      "premium_discount_pct": 0.29,
      "tracking_error_live_pct": 0.12,
      "return_1d": 0.018,
      "return_1w": 0.042,
      "return_1m": 0.15
    }
  ],
  "meta": { "total": 42 },
  "error": null
}

Pipeline Intelligence

PROFESSIONAL Signal analytics and regulatory pipeline monitoring. Returns 402 for Developer and free-tier requests. Rate limit: 100 requests/minute.

GET /v1/pipeline/risk-scores

Review risk assessment for issuers currently under SEC review. Scores reflect how each issuer's review timeline compares to historical patterns. Returns risk level (normal, moderate, elevated, high) and days under review.

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/risk-scores

GET /v1/pipeline/outcome-signals

Approval-pattern signals for issuers in the regulatory pipeline — heuristic scores, not predictions. Each issuer receives a score (1-99) based on filing pattern analysis, with sentiment indicators for contributing factors.

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/outcome-signals

GET /v1/pipeline/accuracy

FREE Public track record for the Approval Likelihood Score — no API key, no payment. Point-in-time backtest aggregates per forecast horizon (30/90/180 days before each outcome, leave-one-out, era-segmented) plus a live layer of scores frozen daily before outcomes are known. Example: 30 days out, 31 of 32 issuers rated 70+ went on to trade. Aggregate statistics only — per-issuer scores are served by /v1/pipeline/outcome-signals above. The score is a heuristic filing-pattern benchmark, not a probability or prediction.

Example

curl https://api.cryptoetfsentinel.com/v1/pipeline/accuracy

GET /v1/pipeline/launch-monitor

Issuers approaching exchange launch. Shows how long each issuer has been waiting post-registration and where they stand relative to historical launch timelines.

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/launch-monitor

GET /v1/pipeline/velocity

Filing velocity tracking for active pipeline issuers. Shows filing counts, types, and activity signals (ramping up, new activity, active) based on recent filing cadence.

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/velocity

GET /v1/pipeline/stalled

DEVELOPER Issuers with no recent filing activity. Useful for identifying applications that may have stalled or been withdrawn.

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/stalled

GET /v1/pipeline/cohort-state

DEVELOPER Per-cryptocurrency cohort wave state. Returns a map keyed by crypto (e.g. bitcoin, solana) describing where each cohort sits in the approval-wave lifecycle.

Each cohort is in one of three states:

holding_pool — no active wave; waiting for the next EFFECT or CERT to anchor a new 50-day window. Issuers with a pending 8-A12B sit at the front of the queue.
in_wave — within 50 days of wave_anchor. Pending issuers in the cohort are wave riders; subsequent EFFECT/CERTs become graduates of the same wave.
cohort_cleared — every cohort member has been approved; no pending issuers remain.

The wave clock anchors on the earliest EFFECT or CERT filing (NOT 8-A12B, which can hang ~50 days before approval). The wave window is fixed at 50 days from anchor; a new wave starts only when an EFFECT/CERT lands more than 50 days after the previous approval.

Response shape

{
  "data": {
    "bitcoin": {
      "state": "in_wave",
      "wave_anchor": "2026-04-15",
      "wave_end": "2026-06-04",
      "latest_approval_date": "2026-04-15",
      "latest_8a12b": "2026-05-03",
      "current_wave_graduate_ciks": ["1234567"]
    },
    "solana": {
      "state": "holding_pool",
      "wave_anchor": null,
      "wave_end": null,
      "latest_approval_date": "2026-01-20",
      "latest_8a12b": null,
      "current_wave_graduate_ciks": []
    }
  },
  "meta": { "total": 2 },
  "error": null
}

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/cohort-state

GET /v1/pipeline/deltas

DEVELOPER Week-over-week changes in pipeline metrics. Shows stage transitions, new filings, and score movements compared to the previous snapshot.

Example

curl -H "X-Api-Key: YOUR_KEY" \
  https://api.cryptoetfsentinel.com/v1/pipeline/deltas

x402 Payments (for AI Agents)

Every paid route is machine-payable over x402 — no subscription, no API key, no human checkout. An autonomous agent pays per call in USDC and gets data back in the same round-trip.

Two payment paths, same URLs. A request with an X-Api-Key header is treated as a human/subscriber and gated by tier (a 402 tier_required points to the Stripe pricing page). A request without an API key is treated as an agent and receives an x402 payment challenge it can settle programmatically. If you are an agent, do not send an API key.

How it works

Agent sends a plain GET to a paid route with no X-Api-Key.
API responds 402 Payment Required with an accepts array (USDC on Base and Solana).
An x402 client signs the payment and re-sends the request with an X-PAYMENT header.
API verifies + settles on-chain via the CDP facilitator, then returns 200 with the data.

Discovery

The machine-readable manifest of every priced route lives at /.well-known/x402. All 22 routes are also indexed in CDP Bazaar discovery. Agents can also read /llms.txt.

402 Challenge (what an agent receives)

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": { "url": ".../v1/agent/issuers", "mimeType": "application/json" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "1000000",
      "payTo": "0x169Bf49c6ee5A179190121Ab8D180B50e31683d1",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "1000000",
      "payTo": "Ezzbt3d3K76pmQpwbeXkggCs5n7Q3JWG3iCmtdKdpMxk",
      "maxTimeoutSeconds": 300
    }
  ]
}

amount is in USDC base units (6 decimals): 1000000 = $1.00. Per-route Bazaar metadata (input/output examples + JSON schema) rides under extensions.bazaar.

Paying a route (x402-fetch)

import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { base } from "viem/chains";

// wallet funded with USDC on Base
const wallet = createWalletClient({ account, chain: base, transport: http() });
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

// no X-Api-Key — the 402 is handled + settled automatically
const resp = await fetchWithPay(
  "https://api.cryptoetfsentinel.com/v1/agent/issuers"
);
const data = await resp.json();

Priced routes & pricing

22 routes across six price bands (USDC, Base or Solana). Full directory + manifest at /.well-known/x402.

Price	Routes
`$1.00`	`/v1/agent/issuers` (full 105+ issuer directory)
`$0.50`	`/v1/pipeline/{risk-scores, outcome-signals, launch-monitor, velocity, cohort-state}`, `/v1/profiles/latest`
`$0.20`	`/v1/agent/filings/recent`
`$0.10`	`/v1/pipeline/{stalled, deltas}`, `/v1/xbrl/{leaderboard, aum-growth, fee-war, fee-war/history, series}`, `/v1/events`
`$0.05`	`/v1/xbrl/issuer`, `/v1/issuers/comment-letters`, `/v1/profiles/history`, `/v1/agent/snapshot`
`$0.03`	`/v1/profiles/comparison`, `/v1/profiles/issuer`

Free/discovery routes (currencies, form-types, stats, filings search, issuers stage preview, query) return 200 with no payment required.

Subscription

Programmatic access to the Stripe-powered subscription flow — this is the human path (agents should use x402 instead). Use these endpoints to create checkout sessions and retrieve API keys after purchase.

POST /stripe/create-checkout-session

Create a Stripe Checkout session for a new subscription. Returns a URL to redirect the user to Stripe's hosted payment page. Rate limit: 5/min.

Query Parameters

Name	Type	Default	Description
`tier`	string	developer	`developer` or `professional`

Example

curl -X POST \
  "https://api.cryptoetfsentinel.com/stripe/create-checkout-session?tier=professional"

Response

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

GET /stripe/checkout-success

Retrieve the API key created after a successful checkout. Poll this endpoint after the user completes payment — returns 202 while the webhook is still processing. Rate limit: 10/min.

Query Parameters

Name	Type	Description
`session_id`	string	Stripe Checkout session ID (e.g. `cs_live_...`)

Response (ready)

{
  "api_key": "sk_dev_a1b2c3d4e5f6...",
  "tier": "developer"
}

Response (pending — 202)

{
  "status": "pending",
  "message": "Webhook not yet received. Retry in 2 seconds."
}

Response Format

All endpoints return a standard JSON envelope:

{
  "data": ...        // Payload (object, array, or scalar)
  "meta": {
    "total": 245,    // Results matching your filters
    "limit": 20,     // Page size
    "offset": 0,     // Current offset
    "page": 1,       // Current page number
    "full_count": 245  // True total (shown when list is tier-capped)
  },
  "error": null      // Error message string, or null on success
}

When a list is capped by tier (e.g. issuers), meta.total reflects the visible count and meta.full_count shows the true total.

Error Codes

Status	Meaning	When
`200`	Success	Normal response
`400`	Bad Request	Invalid parameter or value
`402`	Payment Required	Keyless agents receive an x402 payment challenge; API-key callers below the required tier receive a `tier_required` upgrade prompt
`404`	Not Found	Filing or issuer not found
`422`	Unprocessable	Invalid accession number format
`429`	Rate Limited	Too many requests (see limits below)
`500`	Server Error	Unexpected internal error
`503`	Unavailable	FAISS index not loaded or external service down

402 Response Example (API-key caller below tier)

This is the response when a request with an X-Api-Key hits a route above its tier. A keyless agent hitting the same route instead gets a machine-payable x402 challenge — see x402 Payments.

{
  "detail": {
    "error": "tier_required",
    "required": "developer",
    "current": "free",
    "upgrade_url": "https://cryptoetfsentinel.com/#pricing",
    "message": "This endpoint requires a paid subscription."
  }
}

Rate Limits

Rate limits are per IP address within a sliding 1-minute window.

Category	Endpoints	Limit
Discovery	`/v1/currencies`, `/v1/form-types`, `/v1/issuers`, `/v1/stats`	300/min
Data	`/v1/filings`, `/v1/filings/{accession}`, `/v1/issuers/{cik}/*`	100/min
Search & Query	`/v1/filings/search`, `/v1/query/parse`	100/min
Aggregation	`/v1/query/aggregate`, `/v1/profiles/comparison`	60/min
ETF Financials	`/v1/xbrl/*` (leaderboard, snapshot, series, AUM growth, fee war)	100/min
Pipeline	`/v1/pipeline/*` (risk scores, outcomes, velocity, launch, deltas, stalled)	100/min
Subscription	`/stripe/create-checkout-session`	5/min

When rate limited, the API returns 429 Too Many Requests with a Retry-After header.