auradefi

Open-source, multi-tenant crypto data aggregator. It takes the tenancy model from Vezgo, the DeFi position depth from DeBank and the transaction decomposition from Zerion, then emits Plaid's wire format, so crypto lands in the same downstream schema as bank and exchange data.

It is a library first and a service second. A Python host imports auradefi directly and pays no serialisation or network cost. The HTTP API is a thin shell over the same importable core.

Status: alpha, and 0.1.2 is the release to use. It is 3,426 tests green offline on a fresh clone with no API keys, its notebooks execute clean, and every example under examples/ runs against the published wheel. Work towards 0.2.0 is on main ahead of that release: the EVM node path landed first (a JSON-RPC client, a Multicall3 batcher, a log scanner and a concrete on-chain reader), so this page describes a tree that is not yet a release. STATUS.md carries the live gate state, including which gates are red today.

Do not use 0.1.0. A separate adversarial review of it found nineteen verified defects, of which five were security and four were silent data loss. None of them failed a test. docs/internal/RELEASE_0.1.1.md is the full accounting. 0.1.1 fixes all nineteen and deliberately breaks one id derivation, so read Upgrading in CHANGELOG.md before you move library-ingested data across.

Alpha means the gaps in What is not there are real; read that section before you budget work against this. STATUS.md carries the live gate state, and docs/internal/SPEC.md is the design contract.

Documentation site → carries the examples, the thirteen executable notebooks and the full reference, rendered with every example's real output.

Install

pip install auradefi                # core; httpx is the only dependency
pip install 'auradefi[sql]'         # + the SQLModel ledger backend
pip install 'auradefi[api]'         # + the FastAPI HTTP surface

From a clone (if your system python has no pip, scripts/bootstrap.sh handles it):

git clone https://github.com/auracarehq/auradefi
cd auradefi && bash scripts/bootstrap.sh
.venv/bin/pytest                           # the whole suite, offline, no keys
.venv/bin/python examples/quickstart.py    # every capability, end to end
bash scripts/run_examples.sh               # all thirteen examples

Examples

examples/ holds one file per question. Each one is self-contained, reads nothing from this repository, and runs offline without API keys. Each asserts its own output, and CI executes all of them, so a stale example fails the build.

examples/README.md annotates the index, and the documentation site renders every example with its real output.

Using it

As a library, where the host owns storage, transport, prices and the tick:

from auradefi import Auradefi

auradefi = Auradefi(
    ledger=SqlModelLedger(session_factory=my_session_factory),  # your database
    source=MySource(),        # your transport: .balances() + .fetch_txlist()
    prices=MyPrices(),        # your price feed: .usd_prices()
)
user = auradefi.user("opaque-host-user-id")   # get-or-create, id is derived
user.connect_address("eip155:1", "0x…")       # validated now, not on a later tick
report = auradefi.sync(budget=5)              # budgeted, resumable, self-throttling
holdings, metrics = auradefi.holdings(), auradefi.scalar_metrics()

As a service, where create_app takes ports you already built:

from auradefi.api.app import create_app
from auradefi.api.deps import Deps

app = create_app(Deps(tenancy=…, keys=…, ledger=…, webhooks=…, clock=…))
# POST /auth/token, POST /connections, GET /crypto/sync  (Plaid's envelope)
# GET /coverage, POST /webhooks/endpoints, POST /webhooks/…/replay

docs/books/ walks both surfaces executably and offline.

What works today

Coverage is published as data (rule #10). Every row below has an executable notebook under docs/books/ that runs offline and asserts its own outputs, plus a gate test under tests/.

What is not there

Rule #10 applies to the absences too.

• There are no live network adapters beyond what the cassettes cover. Every I/O path is exercised against committed recordings. Pointing a source at the real Etherscan, Esplora or Solana RPC needs your own keys and endpoints, and CI has not reconciled the output against an incumbent.
• The EVM node path has never met a real node. EvmContractReader, EvmRpc, Multicall3 and scan_logs ship and the five position adapters resolve through them, but every vector that proves it is a hand-authored cassette: the block-20,450,000 words were packed from the integers the existing goldens pin, not recorded from an archive node, and tests/golden/test_phase11_reader.py says so in its own docstring. What is proven is the selector derivation, the word packing, the tuple decode, the block pin and the JSON-RPC path end to end. Agreement with mainnet state at that block is not proven by anything here.
• The codec is static types only: uint<N>, int<N>, address and bool, plus Multicall3's own two dynamic shapes as named special cases. No string, no bytes, no arrays and no nested tuples, and it raises on them instead of guessing. Every function the shipped adapters call fits, and a contract of yours that does not will be refused rather than mis-encoded.
• Nothing in the package constructs an EvmContractReader for you. It is wired by a host, and the block a ResolveContext names is not threaded into the reader: the reader carries its own pin, chosen at construction, so a host that wants a report at block N builds the reader at block N.
• One price oracle (DefiLlama), current prices only. There is no fallback feed and no historical price service: prices/historian.py and prices/store.py are declared in the module layout and absent, as are the coingecko, manual and onchain_amm oracles, so accounting marks are the caller's.
• No scheduler and no background worker. The host owns every tick, and a backfill is a sync() budget you spend yourself. This is the design, not a gap: 0.2.0 removed jobs/ from the declared layout after finding four of its five modules already shipped under other names, and the fifth was a cron evaluator wearing a domain's clothes. What is genuinely missing is a reprocess path for re-decoding stored rows after the decoder improves; the decoder_version it would select on is already persisted.
• Five of the nine declared api/routes/ modules are absent: accounts.py, holdings.py, positions.py, transactions.py and webhooks.py. What ships is auth, connections, sync and admin, so holdings and positions have no HTTP surface of their own, and the webhook admin routes live in admin.py.
• project/ ships only scalar.py. project/plaid.py and project/native.py are declared and absent. The Plaid envelope is projected in api/wire.py instead, so that projection is not reusable outside the HTTP shell the way the layer contract intends.
• Two ledger backends: in-memory and SQLModel/sqlite. Postgres should work through the same port; only sqlite is exercised. The tenancy, keys, quota, audit and webhook stores are in-memory only.
• Cosmos is absent, as is every EVM chain the registry does not seed. So are exchange connections, NFTs and protocol-specific decoders (acts[] is always one act, and protocol is always None).
• Solana transaction decode is not implemented. Balances and signature history only.
• No async surface, no background worker and no scheduler. The host owns the tick.
• There is no migration for the 0.1.1 embed id break. Library-ingested embed connection ids, and every transaction_id hashed over them, re-derive in 0.1.1, so 0.1.0 rows written through Auradefi stop matching. A host either re-derives them itself or accepts the old rows as orphaned history (CHANGELOG.md, Upgrading). Data written through the HTTP API is unaffected.
• SyncStatePort is a five-method Protocol in 0.1.1 (tenants() was added). A host store written against the 0.1.0 four-method shape is refused at bind time, so it cannot silently sync nothing.

The rules the code lives by

• Money is a tagged decimal string, and a raw amount is never a JSON integer.
• Asset ids are deterministic CAIP-19 and permanently stable.
• Every movement is a part[]; fees are siblings of movements.
• Multi-tenancy is designed in. Two tenants can never see each other's data.
• pytest passes on a fresh clone with no API keys, because the cassettes are committed.
• Files cap at 400 lines with no allowlist, and tests/style/ enforces the layer contract.

Docker

docker compose run --rm test    # full offline suite in a network-less container
docker compose run --rm demo    # quickstart against the installed wheel

Docs

auradefi.info is built from this repository, with every example executed at build time and every signature generated from the code.

Start here:

• Quickstart: five lines, no credentials
• Authentication & keys: what you need before mainnet (at most one key, and it is optional)
• Bring your own: your API, your database, your prices, with every port and its methods
• Guides: examples/, thirteen single files that run offline
• API reference: signatures, parameters, return fields, exceptions
• HTTP API: Plaid's wire format, plus openapi.json
• Errors: every exception and its HTTP status
• Build with an LLM: a prompt to paste into a model, plus llms.txt and the whole documentation as one file

Also in the repository:

• docs/books/ holds thirteen executable notebooks, run headlessly in CI.
• CHANGELOG.md records what changed per release, including the 0.1.1 upgrade note.
• docs/internal/ covers how this was designed and built rather than how to use it: the design contract, the pinned algorithms, build status, the 0.1.0 defect accounting, the release procedure and the agent loop that wrote most of it.

Licence

Apache-2.0. See LICENSE.