DIRECT INTELLIGENCE API / V1

Give your AI access
to the evidence.

These endpoints call retained data readers directly. They do not invoke CalyxCash’s generative research model. Your application chooses its own model, reasoning workflow and presentation.

Checking API availability…

1. Create a key and quote a read

In the API console, choose a workspace and permissions, and optionally an expiry and a lifetime spending limit (without one, the key spends from your account balance). Every permission is read-only. Save the key in your server environment as CALYXCASH_API_KEY. Use a discovery-enabled key to inspect GET /v1/capabilities.

Quotes are free. This example requires search:read.

curl https://calyxcash.com/v1/quote \
  -H "Authorization: Bearer $CALYXCASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"records",
       "arguments":{"op":"search_records",
                    "query":"Treasury","limit":3}}'

records is the tool and op picks one of its operations; see Tools and operations. The quote returns a tariff ID and a price in integer micro-USD. 1,000,000 micro-USD = $1. Approve that price in the next call. To execute, add credit to your CalyxCash balance on the Billing page of the console. The same balance pays for API reads and website research questions.

2. Execute under a spending cap

Download the Python helper into your application. It uses only Python’s standard library.

from calyxcash_client import CalyxCash, new_request_key

client = CalyxCash()
request_key = new_request_key()  # save this before sending
result = client.read(
    "records",
    {"op": "search_records", "query": "Treasury", "limit": 3},
    max_price_micro_usd=8000,
    request_key=request_key,
)
print(result["receipt"])
print(result["data"]["data"])

For raw HTTP, send POST /v1/query with tool, arguments, the quoted tariff, and max_price_micro_usd. Add Idempotency-Key: UNIX_SECONDS_UUID_WITHOUT_HYPHENS. A new key must be issued within the last 24 hours; clock skew up to 60 seconds ahead is allowed. Send a descriptive User-Agent header (for example myapp/1.0); requests with an empty or default script user agent such as Python-urllib are blocked before they reach the API.

Tools and operations

The API is organised as tools, each covering one area such as markets, SEC filings, funds or rates and Treasury. Every tool holds several operations. Set op to the operation and pass that operation’s own arguments beside it:

{"tool": "rates_and_treasury",
 "arguments": {"op": "native_funding_rates",
               "benchmark": "SOFR", "limit": 1}}

Each operation keeps its own price, permission, argument schema, qualification and source terms; the tool is only the address. Follow-up routes inside results already use this form, so your agent can pass them back unchanged. Older calls that name an operation directly as tool (for example "tool":"search_records") still work over REST, but the function definitions and MCP list only the tools.

A key sees the tools its permissions can use. Over MCP that is up to 15 tools plus four free helpers. The list below is generated from the live catalogue.

Loading tools…

Connect any model with tool calling

Download the function definitions (one per tool, each with its op list and every operation’s price and permission in its description) or the OpenAPI specification. Supply the definitions to your model and pass its chosen function name and JSON arguments, including op, straight to the API from your own tool runner:

# The function name and arguments come from your model.
# The request key and spending cap come from your application.
packet = client.read(
    tool_name, tool_arguments,
    max_price_micro_usd=20000,
    request_key=saved_request_key,
)
# Return packet to the model, including receipt and provenance.

Keep the API key out of prompts and browser code. A key cannot buy credit, create more keys or change its budget. Source text is evidence, not an instruction to your agent. Preserve stated limitations when forming an answer.

The downloadable definitions cover every operation open to customers. Authenticated discovery also inventories operations still undergoing qualification; an inventory entry does not grant permission to execute it.

Connect an MCP client

Use https://calyxcash.com/mcp with Streamable HTTP and the header Authorization: Bearer YOUR_CALYXCASH_API_KEY. Create a scoped key with a spending limit in the API console. Your client must support a supplied Bearer header; this endpoint does not provide an OAuth sign-in flow. Keep the key in your client’s secret settings, outside prompts.

The endpoint supports MCP 2026-07-28, 2025-11-25 and 2025-06-18. Modern clients use per-request metadata; older clients use initialization. No session ID or persistent event stream is needed.

tools/list returns the tools your key’s permissions allow (up to 15) plus four free helpers: calyxcash_capabilities, calyxcash_prepare, calyxcash_receipt and calyxcash_usage. Calling calyxcash_capabilities needs discovery:read. With every permission that is at most 19 tools, so the list stays small enough for agents to load at startup.

# Claude Code
claude mcp add --transport http calyxcash https://calyxcash.com/mcp   --header "Authorization: Bearer $CALYXCASH_API_KEY"

# Other MCP clients: JSON configuration
{"mcpServers": {"calyxcash": {
  "type": "http",
  "url": "https://calyxcash.com/mcp",
  "headers": {"Authorization": "Bearer YOUR_CALYXCASH_API_KEY"}}}}

1. Call calyxcash_capabilities with no arguments for a compact index of all customer operations, prices, groups and datasets. Then pass tool:"<operation or group>" for exact arguments, qualification limits, source notices and result bindings, or dataset:"<id>" for one complete dataset, its clocks, limitations and entrypoints. These detail reads are free. The index is navigation; read the selected operation before preparing it. Explicit section:"overview" retains the earlier qualification summary, section:"datasets" returns the whole directory, and section:"complete" returns everything GET /v1/capabilities returns.
2. Call calyxcash_prepare with a tool name and its arguments, including op. It accepts tool names only, not bare operation names. This is free and returns an execute object containing the exact tool name, arguments, tariff, price ceiling and request key.
3. Save that object, apply your own spending policy, then invoke the named MCP tool with execute.arguments. Existing key budgets and prepaid credit limits apply.
4. After a lost response, reuse those exact execution arguments. Do not prepare a fresh request to recover an old one. Use calyxcash_receipt when you have a receipt ID; use calyxcash_usage to inspect recent workspace receipts.

// Arguments to calyxcash_prepare
{"tool":"records",
 "arguments":{"op":"search_records","query":"Treasury","limit":3}}

// The result includes the complete execute object:
{"name":"records",
 "arguments":{"arguments":{"op":"search_records","query":"Treasury","limit":3},
              "request_key":"1792874180_cad0…","tariff":"calyxcash-direct-v1-…",
              "max_price_micro_usd":8000}}
// Save it, then send execute.name and execute.arguments as the next tools/call.

Tool results contain one JSON text item with the complete native response and receipt. Parse it as JSON and preserve every source notice, clock and instrument slot. A read still in progress returns http_status: 202; recover its receipt without starting another operation. Disconnecting or cancelling the client does not guarantee cancellation of a committed read or refund: the durable receipt determines its outcome. The MCP request ID is not the billing request key.

MCP adds no surcharge. Prices, source restrictions, response limits and retention are the same as the direct API. The helper tools cannot purchase credit, increase key budgets or access private website research episodes.

TypeScript client

This setup was exercised with @modelcontextprotocol/client@2.3.1. The explicit protocol option matters: this SDK defaults to the older initialization flow. Supply the key from your application’s secret environment.

import { Client, StreamableHTTPClientTransport }
  from '@modelcontextprotocol/client';

const key = process.env.CALYXCASH_API_KEY;
if (!key) throw new Error('Set CALYXCASH_API_KEY');
const client = new Client(
  { name: 'my-research-agent', version: '1.0.0' },
  { versionNegotiation: { mode: { pin: '2026-07-28' } } }
);
await client.connect(new StreamableHTTPClientTransport(
  new URL('https://calyxcash.com/mcp'),
  { requestInit: { headers: { Authorization: `Bearer ${key}` } } }
));
try {
  console.log(await client.listTools()); // No paid read.
} finally {
  await client.close();
}

The older @modelcontextprotocol/sdk@1.32.1 was also exercised using its normal initialization flow. Client applications that only support OAuth connections need a supplied-header integration to use this endpoint.

Choose the population behind the answer

Start with the question and the evidence it needs: a fund’s reported economics, changes between filings, a shared holding reference, a research team or an instrument association. The directory below supplies an exact first request for each documented population.

The same directory is available without charge as retained_dataset_directory in capability JSON and authenticated GET /v1/capabilities. Pass an entrypoint’s tool and arguments to POST /v1/quote, then execute with your application’s spending cap. Discovery does not execute the read.

Pinned snapshots name their expected identity; moving readers return their selected capture and coverage. Some populations overlap. Finite Fed histories, registered BLS captures, OpenAlex and the claims release have separate acquisition paths from the collection registry; an empty registered_source_ids list does not mean missing data. The directory connects Treasury cash, funding rates and six liquidity families to their exact readers. H.4.1 and H.8 currently support catalog and dynamics reads; their cross-series comparisons are not qualified.

Loading documented populations…

{"tool":"research_literature","arguments":{"op":"research_feeds","view":"items","subject":"bitcoin","since":"2026-10-15","until":"2026-10-20","clock":"publication","limit":20}}

client.read("association_map", {
    "view": "statements",
    "source_id": "fed_ddp_macro_econ_reference",
    "other_source_id": "treasury_tic_cross_border",
    "source_pair_only": True,
    "limit": 10
})

overview = client.read(
    "retained_publication_evolution", {"view": "overview"},
    max_price_micro_usd=2000, request_key=new_request_key(),
)["data"]["data"]
route = overview["sources_read"]
sources = client.read(
    route["tool"], route["arguments"],
    max_price_micro_usd=2000, request_key=new_request_key(),
)

Follow a publication reference to its research

Use an associations:read key to connect an attributed publication to separately captured research evidence. The frozen publication selection contains 35,453 revisions from 93 feeds. The target census searched 305,563 retained OpenAlex works and found nine matching works. This is a finite retained selection, not current or complete news coverage.

1. Call retained_evidence_relationships with {"view":"overview"}. Five explicit relation classes stay separate: item history, literal document URL, persistent identifier, complete-text fingerprint and outbound target.
2. Browse {"view":"catalog","method":"outbound_target","limit":10}, or use lookup with the exact locator in key. An absent group_id means no match in this retained prefix. A catalogue describes the entire frozen prefix; it is not a historical snapshot.
3. Open members with the returned group_id and your explicit as_of capture cutoff in Unix milliseconds. The response retains feed, title, revision, native reference pointer and both publication and capture clocks. No occurrence is returned before it was captured.
4. Call retained_reference_targets with view=candidates, that outbound group_id, the same cutoff and one method: literal_document_url, doi_identity, arxiv_explicit_version, arxiv_base_candidates or fragment_document_candidates. Its catalog view can also discover groups with captured research targets.
5. For a candidate with abstract_characters greater than zero, call view=witness with the same selection and its witness_id. Preserve source_reference and source alongside the abstract. Copy next_offset to read the next page; text pages contain at most 1,600 characters. Metadata-only captures refuse an abstract request.

To explore a captured work from another perspective, use its witness.work_id with retained_research_actors, or the record and neighbors views of retained_constellation_associations. Keep an explicit capture cutoff. Each tool has its own retained selection: a work can be present in the reference index and absent from the constellation bank. Preserve that refusal rather than substituting a different work. In the current nine-work reference selection, all nine open through the actor reader and four have constellation records; five remain outside that smaller catalogue.

Relationship overview, catalogue and lookup, and target overview and catalogue cost $0.002 per read. Relationship membership, target candidates and abstract pages cost $0.008 per read. A successful empty page is still a read. Quotes, MCP preparation and receipt recovery are free.

The original census includes 15 native target captures; 12 participate in matched reference routes and nine contain abstracts. Exact-version and fragment policies currently have no matched groups. Base identifiers do not resolve versions, a reference does not establish agreement or endorsement, and capture order is not causation. These explicit links are not admitted learned senses.

OpenAlex data uses CC0; abstracts here are reconstructed from retained OpenAlex metadata. Original publishers remain attributed. The relationship API exposes titles, locators, identifiers, fingerprints and membership. Separate context metadata is available below; publisher article-text witnesses require separate qualification. No linked document is fetched, and OpenAlex's data licence does not license those documents.

Follow a direct link, keep the wider context

retained_relationship_topology opens 180,044 retained records across 23 datasets from Congress.gov, Senate LDA, FEC, Regulations.gov, BLS and FINRA. Of these, 165,306 are eligible for links; reserved records remain visible as context but do not acquire inferred connections. This is a frozen research snapshot, not current coverage of every source.

1. Start with {"view":"overview"} and preserve its identity as snapshot_identity in subsequent requests.
2. Choose one approach: qualified_actor, separate_namespace, cross_dataset, publication_family or clock_context. Use sources to see its datasets, or components to discover networks. Follow the returned members_read and record_read.
3. A record keeps all five memberships and supplies five direct_reads. A links page returns neighbors sharing at least one eligible hub in the selected approach. It does not require agreement in the other approaches, and does not average them into a relevance score.
4. Follow each link_evidence_read to inspect exact shared keys and both records' native evidence coordinates. Follow next_read unchanged to keep the same snapshot, selection and page size. Open the other record to inspect its remaining contexts.

Direct and indirect connections answer different questions. In this snapshot, record 0 has 274 direct qualified-actor neighbors while its connected component contains 43,880 records. Record 2 belongs to that component but shares no direct eligible hub with record 0. A path through a network does not establish a direct relationship.

cross_dataset selects hubs present in more than one dataset; an individual pair may still belong to the same dataset. Namespace views can share neighbors but differ in component membership. Clock links preserve role and coordinate kind: a reporting period is not a publication instant, and a capture time is not an event time. The snapshot has no historical as_of reconstruction. These are explicit evidence views with zero admitted learned senses; they do not establish causation, corroboration or five independent instruments.

Use associations:read. Overview, source and component pages cost $0.002; member, record, evidence and direct-link pages cost $0.008 per successful read, including empty results. Pages contain at most 100 rows. Failed reads and exact request replays add no charge. Preserve provider attribution, source coordinates and the returned source_use notice. FINRA data are attributed to FINRA and supplied under CalyxCash's separately authorized distribution arrangement; no provider endorsement is implied.

Keep the context around a reference

retained_reference_contexts lets your AI inspect five separate selections around the same reference: whole report, reference-local blocks, surrounding blocks, prior revision and cross-source peers. The frozen prefix contains 54,464 context units and 60,443 reference occurrences across 10,961 groups. These overlap the publication selection above; they are not additional documents or five independent learned senses.

1. Open {"view":"overview"} and retain its identity. Discover an outbound group_id with the returned discovery_read through the relationship API.
2. Call view=units with group_id, context_identity and an explicit as_of capture cutoff in Unix milliseconds. Follow next_read without changing its snapshot or cutoff.
3. Each unit supplies five context_reads. Execute the selection your question needs. Each response retains its own fields, blocks, revisions, timestamps, counts and hashes. Multiple candidate blocks remain multiple candidates.
4. Cross-source parts are peer units with their own context_reads; open them separately. Other parts include a witness_read describing the native source-text route, explicitly marked as requiring publisher-text qualification. Customer API views currently include overview, units and parts; witness is refused without a charge.

Overview costs $0.002 per read; unit and part pages cost $0.008 per read, with at most 50 rows per page. A successful empty selection is a read and says no context was eligible in this retained prefix. It does not establish absence elsewhere. Publication time and capture availability remain distinct; a prior revision belongs to its own capture. Whole report means separately retained fields, not a fetched linked article. Peers sharing a reference do not prove agreement, truth or editorial independence. Preserve the returned source notice and every selection's provenance.

Explore a connection without averaging it away

1. Call retained_constellation_associations with {"view":"overview"} to get instrument names, scope and example work IDs.
2. Call its neighbors view with a returned work_id, an explicit as_of knowledge cutoff in Unix milliseconds, and optionally one or more instruments.
3. Inspect each result’s association_instruments and complete readings. A match in one instrument survives differences in the others.
4. Use record for the separate vectors, parts for child measurements, and evidence for the retained source detail.

k is neighbors per selected instrument. All cutoff ties remain available; offset and limit page their union in stable source-address order. This is not a single overall relevance ranking. Child measurements can be opened but do not currently drive neighbor selection.

The association selection contains 305,563 retained research records. These outputs are research observations, with meaning_asserted: false. Five available instrument readings do not by themselves establish five admitted independent senses.

Read dates and provenance as part of the result

A successful response contains receipt, replayed and data. The outer data envelope names the tool, native schema hash, reader observation and native output. Source-specific dates, quantities, identifiers and distinct instrument slots remain inside the native output.

observation.request_started_at_ms is when the reader was called. It is not the publication date, event time or source capture time. source_refresh_forced: false means the read did not trigger a new collection. A historical as_of limits knowledge to records available by that cutoff; it does not imply all events before then were collected.

Coverage is retained and source-specific. An empty selection does not establish absence in the world. An ambiguous category or identity needs a clarifying question before your model selects a final interpretation.

One operation, one receipt

The service reserves quoted credit before reading. It charges after the result is saved with a checksum. Successful empty reads are charged; failed reads are not. Pagination is billed per successful page. Account credit is shared across workspaces, while keys and receipt access are workspace-bound.

• After a network error, reuse the original request key and exactly the same tool and arguments. Never invent a new key just because the response was lost.
• 202 means work is reserved or in progress. Poll GET /v1/receipts/{id}. A disconnected client does not cancel a read that may already have completed; the receipt is the authority.
• A succeeded replay returns its original charge, with no additional charge. A failed receipt also replays unchanged; an intentional new attempt needs a new request key.
• Results remain available for 24 hours. Detailed receipts remain for 30 days, subject to dispute holds. Daily billing totals are retained. An expired result cannot be regenerated by replaying its old request.
• API topups are $20–$500, with no subscription or automatic recharge. They are separate from website research credit and the tools pass. Contact support about unused credit or billing corrections.

GET /v1/usage returns your wallet and 50 workspace receipts. Use both fields of its next cursor for the next page. A refund adjusts your balance; if refunded credit has already been consumed, a negative balance prevents new paid requests. Your one account balance pays for API reads and research questions; when the API side is short, it draws from the rest of your balance automatically.

Read financial observations

Create a key with evidence:read to call treasury_cash_statement, native_funding_rates or retained_claims_release. Each successful read costs $0.008. Treasury cash retains millions of USD and reports its arithmetic reconciliation residual. Funding rates retain their effective dates and distinct secured/unsecured populations. Claims come from one explicitly dated retained release; they are not a promise of the latest release.

client.read("treasury_cash_statement", {"limit": 3},
             max_price_micro_usd=8_000, request_key=saved_request_key)

The durable response includes source_use next to the unchanged native evidence. Retain that notice when presenting or redistributing the data. Source permissions remain those of the source; API charges pay for CalyxCash processing.

The SOFR and EFFR data are subject to the Terms of Use posted at newyorkfed.org. The New York Fed is not responsible for publication of the SOFR and EFFR data by CalyxCash, does not sanction or endorse any particular republication, and has no liability for your use. CalyxCash is not affiliated with the New York Fed. The New York Fed does not sanction, endorse, or recommend any products or services offered by CalyxCash. Source terms · Original data, available without charge.

Positions through time, with a knowledge cutoff

Use positioning_panel with evidence:read to compare a retained CFTC financial-futures market across up to 13 report dates. Each successful call costs $0.008. The panel returns original contract counts, long-minus-short positions, changes between retained reports, and the original source route for every input. It does not invoke a hosted model.

client.read("positioning_panel", {
    "market": "euro_fx", "weeks": 13,
    "reference_fx": "EUR/USD", "as_of_ms": 1792714858560
}, max_price_micro_usd=8000)

as_of_ms is an inclusive Unix-millisecond cutoff on when this system published a retained capture. Both CFTC positions and the FX capture must satisfy it. Omitting the cutoff selects the latest retained retrospective view. A report date or provider row-update time does not establish that this system already knew the value. No eligible capture produces a refusal; absent weeks and missing reference rates remain explicit.

The measured capture history has 11 markets, six distinct reporting weeks and three EUR-base FX pairs. Read coverage for the actual returned population and knowledge for excluded captures. More requested weeks do not manufacture missing history. CFTC participant groups are separate; contract counts across different markets are not comparable dollar exposures. A shared date does not establish a relationship or a cause.

Follow rows[].source_locations through native_source_history and native_source_records to inspect the originals. Date matching uses the same day or an explicitly marked earlier available reference day. Percent changes are CalyxCash calculations. Source: CFTC; Source: ECB statistics via Frankfurter. ECB reference rates are available free from the ECB; API charges pay for CalyxCash access and processing. Preserve the returned source-use notices and the ECB terms.

{"tool":"world_events","arguments":{"context":"gdelt_wikidata","view":"board","scope":"all","limit":20}}

Awards, committees and lobbying disclosures

Start with native_source_history for each source: usaspending_awards, fec_committee_master and lda_lobbying_filings. Discovery costs $0.002 per successful page. Copy the exact generation_id into evidence requests; collection can advance independently. These are bounded retained captures, not every federal award or filing.

1. award_obligations_profile ($0.008, evidence:read) ranks recipients, agencies and individual awards. Follow next_read through the complete rankings; each list reports its own total and page position. Whole-capture totals stay the same across pages.
2. native_source_records ($0.008, evidence:read) opens original rows. For a lobbying row, pass its reference_id and generation to retained_lobbying_filing ($0.008). The response includes the complete original filing: issue descriptions, activity grouping, lobbyists, government bodies, affiliates and foreign-entity disclosures.
3. civic_name_links ($0.002, associations:read) takes references:[{source_id,generation_id}, ...], one for each of the three sources. Follow its original read routes to inspect the disclosed roles. Optional reported_name selects an exact case-sensitive name; next_read pins all three captures.

Award amounts are cumulative obligations, not cash outlays or spending during the query window. Performance dates are not payment dates. Committee records describe registration and connected organizations, not donations; their cycle-start placeholder is not a registration date. Lobbying reports preserve separate reporting, posting and retrieval clocks. Matching names are associations to investigate, not proof of legal identity, corporate affiliation, contact, influence or an award effect.

Sources: USAspending, FEC committee master and Senate LDA. Preserve the returned source-use notices and retrieval dates. FEC use restrictions distinguish individual contributor information from committee records; this API qualification covers the committee master only. Under the LDA terms: Senate Office of Public Records cannot vouch for the data or analyses derived from these data after the data have been retrieved from LDA.gov.

Scheduled releases and ownership filings

Your model can inspect upcoming scheduled releases and the original details of reported ownership. Both readers cost $0.008 per successful page and require evidence:read. Discover a generation first with native_source_generation ($0.002, discovery:read).

For fed_release_calendar, bls_release_calendar or bea_release_calendar, call release_calendar_window with that exact source_id, generation_id, date_from and date_through. The window covers at most 31 dates; follow next_offset for more than 20 entries. Dates follow the source's stated clock. Preserve release_time and release_timezone, including nulls; never assume a missing timezone is UTC. Scheduled entries do not establish that a release occurred and do not contain the released economic values. Repeated calendar entries remain separate.

For sec_edgar_ownership_live, open native_source_records to discover an exact accession_number. Pass it and the generation to native_ownership_document, with historical: true. Its document_sections lists available sections. Select a section and page its records, including nonDerivativeTable, derivativeTable, reportingOwner and footnotes. Missing sections are unknown or absent, never invented zero balances.

XML text and numbers remain original strings. Child arrays and their order preserve the filing's structure. Read each transaction together with its ownership nature and referenced footnotes; a post-transaction balance is not another purchase. Reporting owners are filing-level parties, so their number must not multiply transactions. SEC code P includes both private and open-market purchases. Report periods, transaction dates, acceptance and capture clocks remain distinct. Preserve the returned source_use notice and source URL.

Open original observations and retained revisions

The original-row API covers fourteen qualified sources: Treasury cash statements, auctions and international capital; NYFed reference rates; BEA economic accounts; BLS statistics; Federal Reserve H.4.1, H.6 and H.8; CFTC trader commitments; Fed, BLS and BEA release calendars; and SEC ownership filings. These are the retained selections shown by each source, with their actual coverage. Use a key with discovery:read and evidence:read.

1. Call native_source_generation with the source ID to discover one authenticated capture ($0.002).
2. Copy its exact generation_id into native_source_records, with historical: true to keep that capture stable while collection advances ($0.008 per page).
3. For an earlier capture, call native_source_history ($0.002 per page). Follow its next_before_sequence as before_sequence, then execute a row’s open_arguments through native_source_generation before opening its observations.

# Create and persist one request key per operation before sending.
generation = client.read(
    "native_source_generation",
    {"source_id": "bls_public_api_macro_econ"},
    max_price_micro_usd=2_000,
    request_key=saved_generation_request_key,
)["data"]["data"]

page = client.read(
    "native_source_records",
    {"source_id": generation["source_id"],
     "generation_id": generation["generation_id"],
     "historical": True, "limit": 5},
    max_price_micro_usd=8_000,
    request_key=saved_rows_request_key,
)
print(page["data"]["data"]["rows"])
print(page["data"]["source_use"])

Follow next_offset for the next page. Copy a name from filter_fields and an observed scalar value into filter_field and filter_value for exact selection. A full-artifact row_index is not a returned-page index; record_pointer and native_pointer address the returned packet. Source-native dates, units, revisions and context remain attached.

Revision history is ordered by capture publication, not the economic period inside the rows. Repeated captures can contain the same observations. A pinned historical read does not prove what was publicly available at a past instant. After a reader restart, an undiscovered-history refusal requires restarting discovery; the failed read is uncharged. A new successful discovery is a new priced operation.

Source: U.S. Bureau of Labor Statistics. BLS.gov cannot vouch for the data or analyses derived from these data after the data have been retrieved from BLS.gov. Cite the retrieval date supplied by the native clocks. BLS API terms.

This product uses the Bureau of Economic Analysis (BEA) Data API but is not endorsed or certified by BEA. BEA API terms. Preserve each response’s source attribution and notices when showing or redistributing its observations.

Compare changes across time

Discover a series with liquidity_catalog ($0.002 per page), then copy its complete dynamics_read.arguments.reference into liquidity_dynamics ($0.008 per page). The reference binds the source, capture and series. Use discovery:read and evidence:read; comparisons also require associations:read.

Qualified families are federal_reserve_h6_ddp, federal_reserve_h41_ddp, federal_reserve_h8_ddp, federal_reserve_h6_history, fed_equity_accounts_history, and bls_registered_series. Native captures, finite historical enrichments and registered BLS captures have different coverage and refresh schedules. Read the returned periods and provenance before describing anything as current.

catalog = client.read(
    "liquidity_catalog",
    {"source_id": "federal_reserve_h6_history", "query": "M2", "limit": 50},
    max_price_micro_usd=2_000, request_key=saved_catalog_request_key,
)["data"]["data"]
# Inspect the labels and basis: a matching component is not the M2 total.
matches = [r for r in catalog["rows"] if r["basis"] == "M2.M"]
if len(matches) != 1:
    raise ValueError("Discover the exact seasonally adjusted M2 series first")
reference = matches[0]["dynamics_read"]["arguments"]["reference"]
page = client.read(
    "liquidity_dynamics", {"reference": reference, "latest": False, "limit": 10},
    max_price_micro_usd=8_000, request_key=saved_dynamics_request_key,
)
print(page["data"]["data"]["rows"])
# Follow next_page.tool and next_page.arguments unchanged for the next paid page.

Calculations retain original values, units, input periods, gaps, definition breaks and source coordinates. Stock changes are not measured cash flows. Missing or incomparable observations stay missing; percentage growth requires a suitable positive baseline. latest: true means the last observations in that capture. For a date window supply both period_from and period_through. Capturing a revised history today does not prove that those values were available in earlier years.

To compare two series, discover both exact references, then call liquidity_association ($0.020). Monthly and quarterly series from H.6 native/history, Fed equity history and registered BLS are qualified. Weekly H.4.1 and H.8 remain available for their own dynamics. Choose comparable transformations, such as growth_pct on ratio-scale levels. Mixing monthly and quarterly inputs requires explicit alignment: "quarterly"; the result states how complete quarters were constructed.

# Discover right_reference through its source catalogue first.
comparison = client.read(
    "liquidity_association",
    {"left": reference, "right": right_reference,
     "transform": "growth_pct", "right_transform": "growth_pct"},
    max_price_micro_usd=20_000, request_key=saved_comparison_request_key,
)
for case in comparison["data"]["data"]["cases"]:
    print(case["lag_periods"], case["full"], case["earlier"], case["later"])
print(comparison["data"]["source_use"]["inputs"])

Every comparison includes all seven declared lags, sample counts, earlier/later splits, an exclusion of 2020, and calendar sensitivity. Inspect them together; a strongest lag alone can mislead. These are descriptive associations, not causal findings, forecasts or additional learned instruments. Both input notices remain attached in source_use.inputs and survive receipt replay. Preserve their attribution, dates and usage terms.

Source: Board of Governors of the Federal Reserve System. CalyxCash selections and calculations are separate; no Board endorsement is implied. Federal Reserve source terms. The BLS notice above also applies to registered BLS series.

From a fund report to its holdings

retained_fund_report_comparison opens a finite SEC N-PORT research snapshot: 80 report pairs for 74 funds, covering 154 reports and 127,578 holdings. Use associations:read for this workflow. Catalogue and ambiguity pages cost $0.002; summaries and comparison pages $0.020; original holding and lifecycle-event reads $0.008.

catalog = client.read(
    "retained_fund_report_comparison", {"view": "catalog", "limit": 10},
    max_price_micro_usd=2_000, request_key=saved_fund_catalog_key,
)
pair = catalog["data"]["data"]["rows"][0]
selection = {"pair_id": pair["id"], "as_of_ms": max(
    pair["before"]["observed_at_ms"], pair["after"]["observed_at_ms"])}
summary = client.read(
    "retained_fund_report_comparison", {"view": "summary", **selection},
    max_price_micro_usd=20_000, request_key=saved_fund_summary_key,
)
categories = client.read(
    "retained_fund_report_comparison",
    {"view": "approach", **selection, "approach": "category_bridges",
     "partition": 0, "limit": 10},
    max_price_micro_usd=20_000, request_key=saved_fund_categories_key,
)

Keep the five approaches separate: report totals, individual category partitions, joint category partitions, quantity distributions and lifecycle context. The summary lists the available partitions. Each partition is another view of the same holdings; adding their totals would count money repeatedly. Amounts and scaled integers are decimal strings, so use decimal arithmetic in your model's tools.

Follow a category cell's before.witness_holding or after.witness_holding with view: "holding", the same selection, that side and holding_row. A lifecycle cell's witness supplies table and source_row for view: "event". Only include arguments used by the selected view. For paged views, reuse the selection and the returned next_offset; null means the end.

The ambiguities view preserves competing same-date filings. The reader does not choose one silently. Report dates and capture clocks remain distinct; the cutoff must include both captures, and does not establish first publication time. Changes in reported value are not cash flows, returns or causes. This snapshot is author-checked and has zero admitted learned senses; it does not represent all funds or current holdings. SEC public-filing reuse information. Preserve the returned source notice and coordinates.

Start with the whole Prime-fund picture

money_fund_holdings_profile ranks all 110 manager labels in the retained OFR Prime-fund index, with changes and country, sector and credit concentrations. Use an evidence:read key; a successful profile costs $0.008. Omit period for the latest retained month, or choose an exact month end. The retained window is January 2011 through August 2026. This is a dated capture, not a live portfolio feed.

profile = client.read("money_fund_holdings_profile", {"limit": 10},
    max_price_micro_usd=8_000, request_key=saved_profile_key)["data"]["data"]
target = profile["managers_by_holdings"][0]["record_id"]
page = client.read("money_fund_evidence", {
    "target": target, "period": profile["period"], "limit": 25,
}, max_price_micro_usd=8_000, request_key=saved_evidence_key)["data"]["data"]

Each evidence page costs $0.008. Its summary covers the whole selected manager or credit; rows contains only the requested page. Follow next_offset with the same target and period, saving a separate request key for each page. Each row's source_ref resolves in source_dictionary; selector and previous_selector locate exact cells in the original JSON. A credit's record_id from the profile uses the same tool. record_periods ($0.002, discovery:read) lists supported dates for these two record families.

Changes compare only columns observed in both months. Missing cells stay null; they are not inferred zeroes. Eleven ambiguous routes and ten unavailable routes remain outside the 2,111 reconciled routes, and whole-Prime coverage reports the unattributed amount. Country and sector totals are different partitions of the same holdings; adding them would double-count money. Names are exact source labels, not established legal identities. Holdings changes do not establish investor flows or transactions. Optional known_at_ms on evidence must include the retained capture; it cannot reconstruct earlier publication-time knowledge. Source: OFR Money Market Fund Monitor, based on SEC Form N-MFP. Preserve the returned attribution; no agency endorsement is implied.

Follow reported investor flows through time

retained_money_fund_flows opens the SEC aggregate net investor-flow history: 20 dollar/percentage series, 118 months and 2,360 original observations from October 2016 through July 2026. It requires evidence:read. overview costs $0.002 and lists every supported month and category. The other four views cost $0.008 per successful request or history page.

flows = client.read("retained_money_fund_flows", {"view": "overview"},
    max_price_micro_usd=2_000, request_key=saved_overview_key)["data"]["data"]
month = client.read("retained_money_fund_flows", {
    "view": "month", "period": flows["default_period"],
}, max_price_micro_usd=8_000, request_key=saved_month_key)["data"]["data"]
target = month["categories"][0]["usd_id"]
history = client.read("retained_money_fund_flows", {
    "view": "history", "target": target, "offset": 0, "limit": 50,
}, max_price_micro_usd=8_000, request_key=saved_history_key)["data"]["data"]

month shows the complete category tree, dollar and percentage rankings over six disjoint leaf categories, and exact parent-minus-child accounting residuals. These rankings measure different things: percentages use each category's own lagged assets. Follow next_offset to page a category's complete history, preserving its target and saving a distinct request key per page. Missing observations are never interpolated.

compare requires period and a later compare_period. It returns every original before/after value and their exact dollar or percentage-point difference. evidence requires target and period, and returns the original cell, the other same-month readings, source selectors and definitions. Preserve source_dictionary and each original selector so a model can trace the calculation.

These are net investor-flow aggregates, separate from the Prime holdings view above and from ICI data. A change in monthly net flows is not cumulative flow or asset growth. Do not sum overlapping parents and children or add percentages. Observation months, chart timestamps and capture times remain separate; publication time is unknown. An optional known_at_ms cutoff must include this capture. The snapshot does not reconstruct what was known in an earlier month, and recurring refresh is not commissioned. Source: SEC Money Market Fund Statistics; preserve its attribution.

Compare a manager's reported holdings

Use a key with discovery:read, evidence:read and associations:read for this workflow. sec13f_holdings_comparison compares two report periods for one SEC 13F manager. Each successful comparison costs $0.020. Discover sec_13f_holdings through native_source_generation ($0.002), then open its original SUBMISSION table with native_source_records ($0.008 per bounded page). Copy the exact generation and discovered report periods; use the ten-digit manager CIK, including leading zeroes.

client.read("sec13f_holdings_comparison", {
    "manager_cik": manager_cik,
    "generation_id": generation_id,
    "earlier_period": earlier_report_period,
    "later_period": later_report_period,
    "limit": 10,
}, max_price_micro_usd=20_000, request_key=saved_comparison_key)

A restatement replaces the earlier baseline for its report period. Later supplemental filings add holdings only when the retained chain is complete. The result keeps every selected and superseded accession, distinguishes matched positions from positions present on only one side, and provides original witnesses for the largest changes. Exact matches require security, class, amount type and put/call to agree. Open the named artifact and accession through native_source_records to examine the underlying filing rows.

The current qualified archive contains 3,830,274 holding rows. Tests of the latest two retained periods for 230 managers returned 155 comparisons and 75 explicit refusals for missing bases, duplicate keys, unsupported report types or count mismatches. A refusal is not a zero holding and failed reads are not charged. Report period, filing date and capture time remain distinct; later amendments introduce hindsight. Changes in reported quantities or values do not establish purchases, sales, cash flows or a manager's entire portfolio. Preserve the returned SEC source notice and original dollar/share conventions.

Check the report, then open the original rows

Use retained_report_economics and retained_holdings_relations with an evidence:read key. Economics covers 291 selected reports and 142,279 holdings. The separate holdings index contains 34,950 reported keys, 885,576 N-PORT rows and 3,830,161 13F rows. These are finite retained populations; record numbers and coverage differ between tools. Use the original accession to connect reports, and keep unresolved matches explicit.

reports = client.read(
    "retained_report_economics", {"view": "catalog", "limit": 10},
    max_price_micro_usd=2_000, request_key=saved_economics_catalog_key,
)
report = reports["data"]["data"]["rows"][0]
holding = client.read(
    "retained_report_economics",
    {"view": "holding", "record": report["record"], "holding": 0,
     "as_of": report["observed"]},
    max_price_micro_usd=8_000, request_key=saved_economics_holding_key,
)
keys = client.read(
    "retained_holdings_relations", {"view": "keys", "limit": 10},
    max_price_micro_usd=2_000, request_key=saved_holdings_keys_key,
)
candidate = keys["data"]["data"]["rows"][0]["cusip"]
rows = client.read(
    "retained_holdings_relations",
    {"view": "rows", "cusip": candidate, "source": 1, "limit": 5},
    max_price_micro_usd=8_000, request_key=saved_holdings_rows_key,
)

Economics report preserves separate accounting estimators and controls. holding returns the original value, percentage and residual. corroboration states coverage and the required capture cutoff; valuation compares a selected holding across six amendment-aware approaches. Follow an approach with valuation_witnesses and its method to inspect native rows and version headers. The raw_* views retain the older unresolved-version baseline. Latest retained filings are relative to this archive, not a complete historical portfolio.

The reliability overview and context scenarios are research diagnostics. Simulated changes remain separate from native values. Neither agreement nor a low residual certifies a value or proves authenticity. These explicit calculations have zero admitted learned senses.

Holdings key returns five separate relationship counts. rows uses source: 0 for N-PORT or source: 1 for 13F. A shared CUSIP is a candidate connection: inspect options, quantity units, payoff profiles and report dates. Counts are not independent owners; do not sum different forms or amendments into a portfolio. For catalogue, context, keys and rows pages, advance offset by the number of returned rows until it reaches total.

Discovery, key summaries and diagnostic overviews cost $0.002. Report, holding, row and witness reads cost $0.008. Context and valuation reads cost $0.020. Each successful page is charged separately. The source notice, exact coordinates and limitations stay attached to saved receipts.

Large provenance integers use decimal strings. observation.integer_encoding.paths identifies converted values using JSON Pointers relative to data. Keep them as strings or use arbitrary-precision integers; safe counts and query coordinates remain numbers. Rational amounts already carry exact numerator and denominator strings.

Refusals are part of the contract

Requests are limited to 16 KiB and native results to 2 MiB. A read has a bounded execution time and may refuse. Quotes cover price, not availability or an answer guarantee. The schema describes per-tool page limits.

CALYXCASH_API_NUMBER_PRECISION means a numeric result cannot be transported faithfully through the current JSON path. The read is refused without charge rather than silently rounding it. Please report the tool and receipt ID.