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 and the 0.1.0 release gate was green offline on a fresh clone with no API keys.

Do not use 0.1.0. An independent adversarial review found nineteen verified defects in it — five security, four silent data loss — none of which failed a test. docs/RELEASE_0.1.1.md is the full accounting and 0.1.1 is the fix release, in progress. STATUS.md carries the live test count and which of those fixes have landed; the capability table below says what works today, 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                              # the whole suite, 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: prices/historian.py and prices/store.py are declared in the spec's layout and absent, along with the coingecko, manual and onchain_amm oracles, so accounting marks are the caller's.
• No jobs/ package. The spec 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 rather than in a webhooks.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, which means 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. 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.
• 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 rather than silently syncing nothing.

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
• docs/RELEASE_0.1.1.md — every defect found in 0.1.0, its fix and the regression-test protocol
• CHANGELOG.md — what changed per release, including the 0.1.1 upgrade note

Licence

Apache-2.0 — see LICENSE.