auradefi

Open-source, multi-tenant crypto data aggregator. The tenancy model of Vezgo, the DeFi position depth of DeBank, the transaction decomposition of Zerion, and Plaid's wire format — so crypto merges with bank and exchange data in one schema downstream.

Library first, service second. A Python host imports auradefi directly and pays no serialisation or network cost; the HTTP API is a thin shell over the importable core.

Status: alpha. All ten SPEC phases are implemented — 3,027 tests, green on a fresh clone with no API keys and no network. The capability table below says exactly what that does and does not mean; STATUS.md records the phase gates and known caveats, and docs/SPEC.md is the full design contract.

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 (no pip on your system python? scripts/bootstrap.sh handles it):

git clone https://github.com/auracarehq/auradefi
cd auradefi && bash scripts/bootstrap.sh
.venv/bin/pytest                              # 3,027 tests, offline, no keys
.venv/bin/python docs/examples/quickstart.py  # every phase, end to end

Using it

As a library — the host owns storage, transport, prices and the tick (SPEC §8):

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 — 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

Both surfaces are walked — executably, offline — in docs/books/.

What works today

Coverage published as data, not prose optimism (rule #10). Every row marked works 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

Stated plainly, because rule #10 cuts both ways.

• 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 / Solana RPC needs your own keys and endpoints, and has not been reconciled against an incumbent in CI.
• 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 — there is no eth_call transport and no multicall batcher in the package. A host must supply its own reader to run the adapters against a live chain.
• No multicall anywhere. Token balances cost one request each.
• One price oracle (DefiLlama), current prices only. No fallback feed and no historical price service, so accounting marks are the caller's.
• Two ledger backends: in-memory and SQLModel/sqlite. Postgres should work through the same port; only sqlite is exercised. Tenancy, keys, quota, audit and webhook stores are in-memory only.
• Cosmos is absent, as is every EVM chain the registry does not seed, along with 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, no scheduler: the host owns the tick.

The rules the code lives by

• Money is a tagged decimal string; 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, never 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 — cassettes committed.
• Files cap at 400 lines with no allowlist; the layer contract is enforced by tests (tests/style/), not by convention.

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

• docs/SPEC.md — the design contract
• docs/books/ — twelve executable notebooks, run headlessly in CI so they cannot rot
• docs/DECISIONS.md — every pinned algorithm and id formula
• STATUS.md — phase gates and known caveats
• docs/AGENT_PROMPTS.md — the agent loop that builds this repo, with copy-paste prompts
• docs/RELEASING.md — pip + Docker release procedure

Licence

Apache-2.0 — see LICENSE.