API reference

The surface a host actually touches, in the order it meets it. Signatures, types, defaults and field lists are generated from the code, so they cannot drift from it.

Getting started

The two factories and the object they return.

`Auradefi`	The library's public surface (SPEC §8).
`UserHandle`	One host user's slice of the library (SPEC §7.1, §8).
`Settings`	Settings(etherscan_api_key: 'str \| None' = None, helius_api_key: 'str \| None' = None, http_timeout_s: 'float' = 10.0, sync_min_interval_s: 'int' = 60, project_id: 'str' = 'embed', trusted_proxy_hops: 'int' = 0)

Ports you implement

Bring your own: each is a structural Protocol.

`LedgerPort`	Structural contract for ledger persistence backends.
`SyncStatePort`	Structural contract for embed sync-state persistence.
`BalanceSource`	Structural seam: typed balances for one (chain × address).
`PageFetcher`	Structural seam: ONE page of raw explorer rows for one window.
`PriceOracle`	Structural interface: current USD prices for CAIP-19 asset ids.

Ports we ship

Defaults, so you only implement what you want to.

`EtherscanSource`	Both source seams over one Etherscan V2 client.
`EtherscanV2`	Etherscan V2 balance source over an injected `httpx.Client`.
`DefiLlamaOracle`	Current USD prices from DefiLlama's keyless `coins.llama.fi`.
`Inquirer`	First-wins USD price aggregation over an ordered oracle sequence.
`MemoryLedger`	Dict-backed `LedgerPort` with hard per-tenant isolation.
`SqlModelLedger`	`LedgerPort` over host-owned SQLModel sessions (SPEC §8).
`MemorySyncState`	Dict-backed `SyncStatePort` with hard per-tenant isolation.
`SystemClock`	The wall clock, and the default when a host binds no other.
`FrozenClock`	Deterministic clock for tests; moves only when advance() is called.

Values on the wire

What you get back, field by field.

`Quantity`	An exact base-unit amount: `raw * 10**-decimals`.
`Money`	An exact amount denominated in one currency.
`HoldingsReport`	All holdings of one (address × chain) with an exact USD total.
`Holding`	One asset balance on one account (≡ Plaid Holding).
`SyncReport`	Aggregate result of one `sync()` tick (SPEC §8).
`ConnectionSyncReport`	What one connection's slice of a `sync()` call did (SPEC §8).
`ConnectionRecord`	One watched address bound to a tenant (SPEC §8, §3.1).
`LedgerTransaction`	A persisted transaction: identity, timing, movements, bookkeeping.
`Entry`	One movement of a single asset inside a transaction.
`SyncPage`	One page of sync events, ordered by ascending last-modified seq.

Accounting

Cost basis and PnL at any instant.

`pnl_at`	PnL at an ARBITRARY date. The thing Zerion cannot do (SPEC §9).
`derive_events`	Distil ledger transactions into the taxable event stream (SPEC §9).
`PnLReport`	PnL as of one instant, under one costing method.
`TaxLot`	One open lot in Plaid's `tax_lots[]` shape (SPEC §6.2, DECISIONS

Webhooks

Signing, delivery and replay.

`sign`	Return the `X-Auradefi-Signature` value for `body`.
`verify_signature`	Return `None` iff `signature` is valid AND fresh.
`Deliverer`	Drains due deliveries through an injected `httpx.Client`.
`replay`	Re-arm one delivery; return the NEW PENDING row.