Community data connectors
No-key first success and connector author journey.
TotalFinance's opt-in research contract lets independently maintained provider packages supply price bars and option-chain research. Provider authors own their packages, releases and support. No TotalFinance inclusion PR, central allowlist or listing is required. Ordinary calculations still accept caller data and load no provider, network client or credential.
SDK 0.1.5 includes this provider-neutral preview contract. Earlier SDK 0.1.4 does not contain these subpaths. The independent InsiderFinance provider and its API integration remain private and are not publicly launched; this SDK release does not provide public onboarding or an API key. Start with the no-key source-checkout journey, which builds the local SDK and an independently packed cents-based provider without internal receipts, maintainer paths or credentials. Private reference-provider use requires separately arranged access. An external provider's provisional peer version alone never proves registry compatibility.
Fetch data and calculate
Install SDK 0.1.5 and a separately available compatible provider in the same application. The no-key source-checkout journey builds and verifies a synthetic provider without a public provider package or API access.
Private reference-provider example
The following example is for separately arranged private access. The named InsiderFinance provider package is not publicly distributed and its API integration has not launched publicly; this is not a public npm-install or API-key onboarding flow. Once a compatible provider is available, TotalFinance binds it once, fetches a bounded window and supplies named arrays to existing calculations:
import { data, technicalAnalysis } from '@insiderfinance/totalfinance';
import { createInsiderFinanceProvider } from '@insiderfinance/totalfinance-connector-insiderfinance';
const apiKey = process.env.INSIDERFINANCE_API_KEY;
if (!apiKey) throw new Error('Set INSIDERFINANCE_API_KEY');
const marketData = data.connect(createInsiderFinanceProvider(apiKey));
const prices = await marketData.priceBars({
symbol: 'SPY',
interval: '1d',
from: '2026-09-01',
to: '2026-10-28',
});
const averages = technicalAnalysis.sma(prices.closePrices, { period: 20 });
console.log(averages.at(-1));The environment variable is read by your application, never by TotalFinance. The private connector preview defaults to the documented staging origin, native fetch and response-receipt clock; fetch/now/baseUrl overrides remain optional. Construction and local discovery cause no HTTP reads. Configure access and a new request allowance before real reads. The exact installed example is verified with synthetic one/multiple-page HTTP facts, not a live-data receipt. There is no MCP/server/pack prerequisite.
priceBars returns only after terminal pagination, or throws a typed refusal. Defaults are
pageSize1000, maxPages20, maxReads21 (including one capability discovery) and maxRecords20000.
These are HOST work ceilings, not financial assumptions, provider maxima or paid request credits.
The host hard limits are10000 rows/page,100 pages,101 invoked reads and100000 records, with bounded
canonical work/bytes. Call options may lower connection ceilings. There are no automatic retries,
background reads, fallback query or cache. An exhausted window is never a partial success.
The ordinary named arrays are frozen native arrays. closePrices feeds existing SMA/SMA.explain.
ohlcvBars supplies OHLCV for VWAP; bars supplies canonical timestamped Bar records with actual
volume, source adjusted flags and supplied vwap. Unknown volume blocks strict OHLCV/bars only,
never zero-fills or needlessly blocks valid closes. Partial quality is not a blanket refusal.
selections lists these choices without evaluating lazy getters; JSON serialization is safe even
when volume is unknown. For an engine that takes ownership of a mutable array, use an ordinary copy:
const result = backtest.vectorized({ ...explicitBacktestOptions, data: [...prices.bars] });
const sampled = technicalAnalysis.resample(prices.bars, explicitInterval, explicitOptions);Source pages stay in prices.window.pages, with every timestamp, warning, quality/coverage,
identity and basis fact. Store prices.window and, after any explicit decision, prices.selection.
data.createPriceBarsWindowView(savedWindow, savedSelection) restores without a provider. Terminal
paging does not certify continuous history, point-in-time availability, live liquidity or enough
rows for a chosen period. Pure engine results do not automatically inherit source metadata.
Author a minimal source, use one common SDK normalization
The no-key starter maps a genuinely different cents-based vendor schema using public imports. The copied independent Alpaca-style example keeps actual 04Z daily timestamps and passes vendor page tokens directly. Both have their own install boundary, lock and independently expected records/pages. Original independent review observations are unchanged.
A factory returns DataProviderSource, protocol totalfinance-data-source, contractVersion2.
data.connect(source) is the consumer handoff; defineDataProvider(source) from /core/data is
an advanced one-page consumer binding. Do not return a consumer wrapper from a source factory.
Construction performs no discovery/network work. The SDK owns common metadata/provenance stamping,
unknown clocks and immutable projections; the external package owns auth, HTTP, cancellation and
source mapping, with at most one vendor request per source query and no hidden retries.
The raw source implements:
capabilities(options?: DataCallOptions): Promise<readonly DataCapabilityDeclaration[]>;
query(query: DataQuery, page: DataPageOptions): Promise<SourcePriceBarsPage | SourceOptionChainPage>;Every query call receives the same original financial query plus separate
{limit,cursor:string|null,pins:DataPins|null,signal?}. Authors supply actual rows and per-page
facts: dataset id/version, receipt time, adjustment, consistency and bar timestamp convention.
Dataset/basis/consistency may differ between queries; they are not global provider defaults.
Optional absent clocks/freshness/coverage remain unknown. No rates, IV, roots, multipliers or
financial adjustments are invented. Unsupported capabilities refuse explicitly.
Discovery declares finite understood intervals:1m,5m,15m,30m,1h,4h,1d,1w,1mo. Intraday bounds are inclusive zoned instants; day/week/month bounds are inclusive session labels. Unknown safe future tokens such as1s are ignored with counts while supported ones remain available. Malformed known declarations still refuse. Provider ceilings may exceed host limits. InsiderFinance currently supports daily/minute bars with its own2000-row and minute31-day restrictions; those are not universal SDK vendor laws. Its chains remain incomplete EOD research.
Advanced marketData.query(originalQuery,{limit,cursor?,signal?}) is one page, zero discovery.
For manual continuation pass its view.continuation, never construct a cursor-only financial query.
A v2 canonical page stores exact original query and provider id/version so JSON restoration can
recreate the continuation. A legacy v1 restored nonterminal page explicitly cannot reconstruct it.
All original bounds/filters/pins/identities/order and temporal conventions remain validated.
The public fixture and common kit use the same boundary.
Deliberately resume failed work
try {
await marketData.priceBars(request);
} catch (error) {
const checkpoint = data.priceBarsCheckpoint(error);
if (!checkpoint) throw error;
await savePrivateCheckpoint(JSON.stringify(checkpoint));
}
// A deliberate host decision, possibly after resolving access/rate/allowance conditions:
const prices = await marketData.resumePriceBars(JSON.parse(await loadPrivateCheckpoint()));Checkpoints are separate private storage, never serialized into public error text/context. They retain validated accepted pages, original binding/query/cursor/pins, paging policy and consumed reads/pages/records. Resume validates these before I/O, negotiates one fresh discovery and never refetches accepted pages. Failed/aborted invoked reads remain consumed; pre-dispatch abort costs0. Accepted zero-row nonterminal pages retain their cursor and pins. No crash-atomic or upstream idempotency guarantee is made; a repeated failed page can incur another vendor charge.
A new connection's larger DEFAULT does not raise saved budgets. Only explicit permissible constructor/resume increases authorize more HOST work, never provider credit. Resolved page size stays pinned and must fit current connection/provider/hard ceilings. Automatic unresolved sizing negotiates min(saved base1000,current connection ceiling,provider maximum). A smaller ceiling or expired source pin can refuse; no cursor restart, hidden counter reset or new allowance is granted.
Explicit choices for suspect finite observations
Finite contradictory OHLC is acquired unchanged with controlled issues (page/row/rule/fields).
A selector stops with data.suspect_observations only when an unresolved issue affects a field it
uses. For high<close, the SDK cannot know which operand is wrong. Valid closes with an unrelated
open-only issue stay usable. Essential identity, nonfinite required data, adjustment/filter/pin
contradictions and negative normalized option premiums remain hard refusals.
console.log(prices.issues);
const chosen = prices.resolve({ action: 'exclude', reason: 'Independent research review' });
const averages = technicalAnalysis.sma(chosen.closePrices, { period: 20 });
console.log({ averages, decisions: chosen.selection, source: chosen.window.pages });resolve({action:'use',reason}) deliberately retains questionable inputs; existing pure leaves
still enforce their own validations. correct requires explicit finite OHLC replacements and a
reason; it never changes raw source rows or invents volume/identity/time. Selections retain ordered
source-row correspondence and explicit decisions; exclusion does not imply continuous history or
sufficient lookback. Persist source and selection separately to revalidate/replay them on restore.
Read the metadata before computing
A daily source timestamp can be04Z/session-start, or midnight UTC can be a session-date label. Keep its declared convention and explicit session label; neither is observation or availability. A minute bar's interval start is separate from source receive/observation time. Source storage, API generation, host receipt and first public availability are separate facts. Null means unknown; fetching now never supplies the missing historical instant. The existing Provenance record carries only clocks actually known.
Source quality complete does not prove continuous historical coverage. Bounds can enclose a long
gap; missing sessions/minutes are not filled. Keep the returned source issues, observed-only
coverage and adjustment basis with any analysis. Split-only prices are not dividend-adjusted total
returns. Every protocol2 capability is research-oriented: pointInTime: false and
executionEligibility: 'research-only' grant no liquidity or trade eligibility guarantee.
An incomplete chain acquisition record is deliberately different from a complete OptionQuote.
It retains source IDs, missing terms, quotes, supplied Greeks and diagnostics. It does not invent
listed roots/OCC symbols, multipliers, exercise/settlement style, exact expiry or valuation time,
rates or volatility. Source model price remains separate from observed quote fields. Obtain missing
inputs independently and validate them through the existing public builders before pricing; this
contract offers no automatic pricing, market-snapshot or fill conversion.
Verify an external package
Provider implementations import the public SDK just like any application. Keep credentials and HTTP mappings in the independent provider package. The maintained InsiderFinance package uses this same route; it is not an exception or an internal workspace advertised as installable.
Run the framework-independent kit against hand-authored expected pages and error/abort probes. Pin receipt clocks, provider identity and opaque cursor constants explicitly. Test capability truthfulness, ordering/identity within and across pages, source pins, finite/null/zero handling, input immutability, bounded walks, cancellation, access/rate-limit errors and error redaction. Expected metadata may differ by provider; do not erase financial, temporal or quality differences to make a comparison pass. A kit that cannot reject one-defect provider mutants proves little.
Pack and install both SDK and provider in a clean consumer with no workspace aliases. Compile with
NodeNext and Bundler resolution, execute ordinary ESM, verify the registered safe error contract across separately installed SDK copies and run the
same research workflow against fixture and HTTP implementations. The explicit local rehearsal is
tools/community-connectors-provider-smoke.ts; its inputs are two supplied tarballs and synthetic
tests, never credentials. Offline fixtures establish mapping behavior, not upstream deployment,
actual entitlements, historical completeness, licensed redistribution or a real-agent result.
Authentication, entitlement, throttles, exhausted allowance, snapshot expiry, cancellation and service/data failures have distinct registered codes. Retry advice is metadata; the connector does not issue a second request. API-01's published pagination instructions remain a separate app/API task. API-02–05 coverage, temporal model, freshness and methodology findings remain source-qualified limits rather than an invitation to rewrite the server or invent missing inputs.
Portable provider refusals preserve the registered data/access codes and only these existing general input codes: input.wrong_type, input.missing_field, input.not_finite, input.out_of_range and input.invalid_enum. The SDK rebuilds its own error text/class and retains the original cause locally. Use DataProviderError with explicit controlled guidance for public field/rule teaching; arbitrary provider messages, contexts and causes are never forwarded as public diagnostics. Unknown codes and network throws remain data.provider_failure. The kit checks the same protocol across SDK copies.