Start from the public contract, not provider payloads

An integration should depend on the versioned ChainsFlow API schema instead of Binance, Bybit, Kraken or OKX response shapes. The API keeps provider DTOs behind adapters and exposes stable portfolio and balance resources. Generate typed clients from OpenAPI where useful, but keep a small application-owned wrapper so version upgrades and error mapping remain deliberate.

Keep end-user ownership in your BFF

Create a portfolio through POST /api/v1/portfolios and store the returned opaque portfolioId beside your local user. ChainsFlow API sees only the authenticated API account and its portfolio resources.

Treat exchange connections as long-lived resources

A connection contains encrypted read-only credentials, synchronization status and normalized holdings. Create it from your server, retain the returned account ID and show explicit syncing, active or error states to the user. Never proxy exchange secrets through analytics, support tooling or client-side logs, and provide a clear delete action when the user disconnects an exchange.

Read accounts and aggregate views for different jobs

Account endpoints are useful for provider status, exact balances and connection management. The portfolio endpoint combines supported accounts into one USD view with allocation and market-implied 24-hour movement. Performance is separate because it depends on stored snapshots and cash-flow coverage. Choosing the narrowest endpoint reduces credit use and keeps UI loading states understandable.

Add budgets, observability and graceful degradation

Record X-Credit-Cost, X-Credits-Remaining and correlation IDs without logging credentials. Set bounded timeouts, respect Retry-After and distinguish a provider failure from an authentication or credit failure. Cache only data whose staleness the product can explain. A portfolio screen should remain useful when one exchange is temporarily unavailable instead of presenting the entire user workspace as lost.