Quickstart
Make your first Orion API call — one request returns a wallet's DeFi positions across every supported Stellar protocol.
One request resolves a wallet’s positions, USD value, yield, and health across Blend, Aquarius, and Soroswap in a single normalized response — you never talk to each protocol on its own terms. This page takes you from zero to a first response.
Base URL
https://query.orionhq.runAuthenticate
Every request carries your API key in the x-orion-api-key header. Keys are
per-organization; Authentication & API keys covers
how to obtain one.
export ORION_KEY="sk-orion-...your-key..."Your first call
Fetch every position for a wallet with GET /v1/users/{address}/positions:
curl https://query.orionhq.run/v1/users/GABC7XYZ.../positions \
-H "x-orion-api-key: $ORION_KEY"The response has three top-level parts — data, enrichment, and meta:
{
"data": {
"address": "GABC7XYZ...",
"total_value_usd": "1482.55",
"aggregate_net_apy": "0.0413",
"aggregate_health_factor": "1.87",
"protocols": [
{
"protocol_id": "blend",
"deposited_usd": "1620.00",
"borrowed_usd": "137.45",
"net_apy": "0.0413",
"health_factor": "1.87",
"estimates": {
"borrow_cap_usd": "1053.00",
"borrow_limit_pct": "0.13"
},
"positions": {
"collateral": [
{
"asset_id": "CAS3J7GY...",
"contract": "CCLBPEYS...",
"share_amount": "1600.0000000",
"asset_amount": "1620.0000000",
"usd_value": "1620.00",
"share_type": "bToken",
"apr": "0.0221",
"liquidation_price": null,
"metadata": null
}
],
"liabilities": [
{
"asset_id": "CDLZFC3S...",
"contract": "CCLBPEYS...",
"share_amount": "137.0000000",
"asset_amount": "137.4500000",
"usd_value": "137.45",
"share_type": "dToken",
"apr": "0.0587",
"liquidation_price": null,
"metadata": null
}
],
"supply": [],
"lp": [],
"backstop": []
}
}
]
},
"enrichment": {
"contracts": {
"CCLBPEYS...": {
"protocol": "blend",
"name": "Fixed V2 Pool",
"version": "v2",
"status": "active",
"position_types": ["supply", "collateral", "liability", "backstop"]
}
},
"assets": {
"CAS3J7GY...": {
"symbol": "XLM",
"decimals": 7,
"tags": ["native"],
"price_source": "pool_oracle",
"price_usd": "1.0125"
}
}
},
"meta": {
"data_staleness_seconds": 4,
"last_indexed_ledger": 3356416,
"oracle_staleness_seconds": 12,
"partial_result": false,
"sources": ["soroban_rpc"],
"attribution_confidence": 1.0,
"response_time_ms": 18
}
}Reading the response
| Part | What it holds |
|---|---|
data | The positions themselves — one entry per protocol, each split into collateral, liabilities, supply, lp, and backstop buckets. |
enrichment | Lookup tables for the contract and asset_id values inside data — human names, symbols, decimals, and the price source used. |
meta | Freshness and provenance for this response, including last_indexed_ledger — the ledger the data reflects. |
Every dollar amount, rate, and share is a string, not a float, to preserve full on-chain precision. Parse with a decimal type.
meta.last_indexed_ledger is how you reason about freshness and pin a read to an
exact point in chain history — see
As-of-ledger & staleness.
Next steps
- Authentication & API keys — obtain and manage keys.
- Positions concepts — health factor, borrow limit, LP breakdown, and why values are stored rather than computed at read time.
- Protocol coverage & registry — which protocols are supported and what each exposes.
- Activity taxonomy — the normalized event feed.