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.1 is the release to use. Every planned capability is implemented. The suite is 3,247 tests green offline on a fresh clone with no API keys, all twelve notebooks execute clean, and every example under examples/ runs against the published wheel.

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 twelve 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 eleven 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.
• Positions are fixture-driven. The ContractReader seam ships and every adapter is pinned to block-20,450,000 golden vectors, but no concrete on-chain reader ships. The package has no eth_call transport and no multicall batcher, so a host must supply its own reader to run the adapters against a live chain.
• There is no multicall anywhere, so token balances cost one request each.
• 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 jobs/ package. The layout declares scheduler.py, discover.py, refresh.py, reprocess.py and backfill.py; none of them ship. There is no scheduler, no background worker and no reprocess path. The host owns every tick, and a backfill is a sync() budget you spend yourself.
• 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/, eleven 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 twelve 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.