River: Buy Bitcoin — API integration, OpenFinance protocol analysis & Lightning data services

Why River data matters for OpenFinance

Unlike generic crypto wallets, River behaves as a regulated US financial institution: USD funds are deposited with Lead Bank (FDIC-insured to $250,000), bitcoin is held in full reserve with multi-sig cold storage, and all customer activity is settled against structured ledgers. For OpenBanking-style integrations, this means every balance, statement, and payout event is tied to a known USD bank rail and an auditable on-chain custody layer — a combination that most crypto apps do not expose.

Because River is Bitcoin-only, there is no altcoin noise to filter. Accounting teams, wealth platforms, and high-net-worth back offices can consume one clean feed of cost basis, tax lots, interest-in-BTC accruals, and Lightning-route payments and reconcile it directly against 1099 documents and on-chain proofs.

Who this integration is for

• Wealth RIAs and family offices that need consolidated BTC + USD reporting alongside brokerage accounts.
• Accounting Bookkeeping and tax platforms that ingest cost-basis and proceeds rows for Form 8949.
• Fintech Neobanks and budgeting apps offering a unified "cash + Bitcoin" view.
• Corporate treasury Firms that dollar-cost-average corporate reserves into Bitcoin via the API.
• Developers Builders who want a compliant Lightning payment rail backed by a US-regulated custodian.

1. Authenticated account login

Mirror River's mobile authentication flow (email / password, TOTP 2FA, device attestation) and expose a stable POST /river/auth/login endpoint that returns a short-lived access token plus a refresh token. Used by backend jobs to attach to a customer account under explicit, revocable consent.

2. Balance & holdings snapshot

Single-call GET /river/accounts/{id}/balances returning settled USD, pending USD, BTC (satoshis), cost-basis aggregates, and unrealized P&L. Used by dashboards, reconciliation jobs, and portfolio allocators that merge River into a multi-venue view.

3. Transaction & statement API

Paged GET /river/transactions with filters for buy, sell, recurring, interest, on_chain_send, on_chain_receive, lightning_send, lightning_receive, and river_link. Every row carries a cost-basis lot reference, fee structure, and tx hash or payment preimage where applicable — drives tax reports and audit exports.

4. Recurring buys & Supercharged scheduling

Programmatic create/update of recurring-buy rules (hourly, daily, weekly, bi-weekly, 1st & 15th, monthly) with Supercharged multipliers released in October 2025 — trigger when BTC trades ≥1% below a moving average and scale the buy 25–100%. Perfect for treasury DCA engines.

5. Lightning & on-chain payments

Generate BOLT11 invoices, pay lightning invoices, request on-chain withdrawals to allow-listed addresses, and receive webhook deliveries on payment settlement. Enables River-backed Lightning checkout, payroll in sats, and remittance flows.

6. Interest & Proof-of-Reserves feed

Stream River's USD cash interest accruals (payouts configurable in USD or BTC) and consume the Proof-of-Reserves attestation feed, so downstream systems can independently verify that customer BTC is held 1:1 in multisig cold storage.

Scenario 1 — Unified wealth dashboard

Business context: A US-based RIA manages households that hold traditional brokerage plus Bitcoin at River. Advisors need a single "net worth" view refreshed nightly.

Data / API: GET /accounts/{id}/balances, GET /transactions?types=buy,sell,interest, plus the Proof-of-Reserves feed.

OpenFinance mapping: Treated as a non-bank financial institution feed; consent lifecycle follows FDX-style scoped permissions (balances, transactions, statements), with explicit re-consent every 12 months.

Scenario 2 — Crypto accounting & tax

Business context: A bookkeeping platform imports every taxable event — buys, sells, interest-in-BTC, on-chain sends — and produces Form 8949 and 1099-style summaries.

Data / API: GET /transactions?types=* with cost_basis_lot, fee, proceeds_usd, acquired_at; plus GET /statements/{year} for reconciliation.

OpenData mapping: Standardised into a JSON ledger that downstream tools (QuickBooks, Xero, Bitwave) can ingest alongside exchange data from Coinbase or Kraken.

Scenario 3 — Corporate DCA treasury

Business context: A company allocates a fixed % of weekly cash flow to Bitcoin reserves, with a board-approved drawdown-protection rule.

Data / API: POST /recurring-buys with a weekly cadence and a Supercharged multiplier that doubles orders when BTC trades ≥1% below its 200-day moving average; GET /recurring-buys for audit.

OpenFinance mapping: Integrates into the firm's ERP as an automated payment instruction plus a custodial position report.

Scenario 4 — Lightning payroll & remittance

Business context: A global payroll platform pays contractors in sats via Lightning, backed by a US-regulated custodian.

Data / API: POST /lightning/invoice (generate), POST /lightning/pay (send), webhook lightning.payment.settled for reconciliation, and GET /balances to fund outgoing runs.

OpenData mapping: Payment metadata (memo, preimage, route) is normalised and stored alongside fiat payroll events for unified reporting.

Scenario 5 — Compliance & Travel Rule packaging

Business context: A compliance vendor must monitor on-chain withdrawals ≥ $3,000, run address screening, and deliver originator/beneficiary information per the BSA Travel Rule.

Data / API: Webhook onchain.withdrawal.requested, plus GET /transactions?types=on_chain_send&min_amount_usd=3000; fields include counterparty address, memo, and risk score.

OpenFinance mapping: Produces a FinCEN-ready audit trail that can be forwarded to Chainalysis / TRM screening and, where applicable, to IVMS 101 Travel Rule messaging.

Authentication & session exchange

POST /api/v1/river/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "***",
  "totp": "123456",
  "device_id": "ios-7a9b..."
}

// 200 OK
{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rt_...",
  "expires_in": 900,
  "account_id": "acct_r1v3r_01HX..."
}

Bitcoin + cash statement query

GET /api/v1/river/transactions
?account_id=acct_r1v3r_01HX
&types=buy,sell,interest,on_chain_send,lightning_receive
&from=2025-01-01&to=2025-12-31
&cursor=eyJwYWdlIjoyfQ
Authorization: Bearer <ACCESS_TOKEN>

// 200 OK (excerpt)
{
  "items": [
    {
      "id": "tx_01HZ...",
      "type": "interest",
      "asset": "BTC",
      "amount_sats": 2145,
      "usd_accrual_cents": 187,
      "occurred_at": "2025-11-02T09:14:22Z",
      "statement_id": "stmt_2025_11"
    },
    {
      "id": "tx_01HZ...",
      "type": "on_chain_send",
      "amount_sats": 5000000,
      "counterparty_address": "bc1q...",
      "txid": "9f1c...",
      "fee_sats": 1840,
      "travel_rule_required": true
    }
  ],
  "next_cursor": "eyJwYWdlIjozfQ"
}

Lightning payment webhook

POST /your-endpoint/webhooks/river
X-River-Signature: t=1732000000,v1=5d41...

{
  "event": "lightning.payment.settled",
  "account_id": "acct_r1v3r_01HX...",
  "invoice": {
    "bolt11": "lnbc2500n1p...",
    "amount_sats": 250,
    "preimage": "b1c2...",
    "memo": "Invoice #8821",
    "settled_at": "2026-04-20T12:00:00Z"
  }
}

// Verify HMAC, then credit order #8821.

Error handling & rate limits

Standardised error envelope with error.code, error.message, trace_id. Rate limits are communicated via X-RateLimit-Remaining and Retry-After. Retries use idempotency keys (Idempotency-Key: <uuid>) so recurring-buy and Lightning-pay calls are safe to replay.

// 429 Too Many Requests
{
  "error": {
    "code": "rate_limited",
    "message": "Too many statement queries",
    "retry_after_ms": 1200
  },
  "trace_id": "tr_01HZ..."
}

Compliance & privacy

River Financial Inc. operates as a US Money Services Business (MSB) under FinCEN Bank Secrecy Act (BSA) obligations: KYC/CIP at onboarding, SAR filing for suspicious activity ≥ $2,000, CTR filing for cash activity above $10,000, and the Travel Rule for crypto transfers above $3,000. USD balances are held at Lead Bank (Member FDIC) and subject to FDIC insurance rules up to $250,000 per depositor.

Our integrations layer additional privacy guardrails on top of that baseline: explicit, revocable user consent, scope-limited OAuth tokens, data-minimization (we only pull what a use-case requires), per-account audit logs, encryption in transit (TLS 1.2+) and at rest (AES-256), and a retention clock aligned with the customer's regional law — GDPR and UK GDPR where EU/UK residents are processed, and state-level rules such as CCPA / CPRA for California. Penetration tests and SOC 2-style controls are available on request.

We do not bypass River's authentication or custody model. Every integration is built on top of authorized user sessions or documented public endpoints, and we refuse engagements that would require circumventing 2FA, scraping other users' data, or moving funds without an owner's signed consent.

Data flow / architecture

A typical River integration follows a clean four-node pipeline. No node stores raw credentials outside a dedicated KMS-backed secret store; every hop is signed, audited, and replay-protected.

• Ingestion: scheduled pulls (balances, statements) plus push webhooks (payments settled).
• Normalization: unified schema for buys, sells, interest, Lightning, and on-chain events.
• Delivery: REST API, CSV/JSON exports, or managed webhooks to customer endpoints.

Swan Bitcoin

US-regulated Bitcoin-only broker offering instant buys, recurring buys, Swan IRA, and institutional-grade Swan Vault. Users who keep retirement allocations at Swan often ask for unified DCA and cost-basis exports alongside River.

Strike

Consumer app built on the Lightning Network with direct-deposit salary conversion, bill pay, and 0.49% buy fees. Frequently paired with River for businesses wanting a payments rail plus a long-term custodial reserve.

Cash App

Block's peer-to-peer payments app with native Bitcoin buy/sell and Lightning send. Appears in almost every US consumer ledger; integration needs center on combining Cash App Bitcoin activity with River cost-basis and interest feeds.

Fold

Bitcoin rewards debit card and app that accrues sats on everyday spend. Merging Fold's reward events with River holdings produces a clean "earn + save" dashboard.

Relai

FINMA-regulated, non-custodial European Bitcoin-only app focused on SEPA DCA. Ideal counterpart to River for users who sit across US and EU payment rails and need consolidated lot tracking.

Bitstack

European round-up app that converts spare change into Bitcoin. Typical integration need: aggregate round-up buys with River's scheduled zero-fee DCA for a single cost-basis ledger.

Coinbase

Large US exchange offering Bitcoin plus many altcoins. When Coinbase sits alongside River, integrations usually filter to BTC-only rows and align with River's tax-lot schema.

Kraken

US/EU exchange with deep liquidity and staking. We regularly normalise Kraken's trade and ledger exports into the same JSON shape our River connector emits, so treasury teams see a single view.

Casa

Multisig self-custody platform for high-net-worth individuals. Pairs with River Private by feeding custody health and inheritance plan data alongside River's Proof-of-Reserves output.

Unchained Capital

Collaborative-custody vault and Bitcoin-backed lending provider. Integrators often want to combine Unchained's vault balances with River's liquid BTC and cash interest in one report.

Deliverables checklist

• OpenAPI 3.1 specification for every exposed route (login, balances, transactions, recurring-buys, Lightning)
• Protocol and auth flow report (token lifecycle, 2FA handling, device attestation)
• Runnable reference implementation in Python and Node.js (FastAPI / Express) with Docker Compose
• Automated pytest / Jest suites, mocked River fixtures, and contract tests
• Webhook signature verification module (HMAC-SHA256 with clock skew tolerance)
• Compliance addendum: BSA/FinCEN obligations, GDPR/CCPA checklist, retention matrix
• Operator runbooks: token rotation, incident response, replay scripts

Engagement models

• Source code delivery — from $300. You receive the full repo, tests, and docs; you pay after delivery upon satisfaction. Best when you want to own, audit, and self-host the integration.
• Pay-per-call API billing. Route traffic to our hosted endpoints and pay only for the calls you make; no upfront fee, no seat licence. Ideal for pilots, low-volume apps, or teams that prefer usage-based pricing.

Long-tail capabilities we cover

• River Bitcoin transaction export and statement API integration
• Bitcoin-only OpenBanking / OpenFinance data connector
• Lightning Network invoice API with webhook settlement
• Zero-fee recurring-buy automation and Supercharged DCA rules
• FDIC-insured USD cash balance and interest-in-Bitcoin payout feed
• Proof-of-Reserves attestation ingestion for audit dashboards

About our studio

We are an independent technical service studio specialising in mobile app interface integration, authorized API delivery, and fintech protocol analysis. Our engineers have shipped production code inside banks, crypto exchanges, Lightning payment processors, and cross-border payment gateways, so we understand what "production grade" means for regulated financial data.

Every engagement follows the same path: protocol analysis → build → validation → compliance sign-off. We work under NDAs where needed, refuse anything that requires bypassing multi-factor authentication, and default to the narrowest scope that still solves the business problem.

• Payments, digital banking, Bitcoin exchanges, crypto accounting, and cross-border clearing
• Enterprise API gateways, OAuth 2.1 / OIDC, mTLS, HSM-backed signing
• Python, Node.js, Go, Kotlin, and Swift SDKs with first-class test harnesses
• Source code delivery from $300, or pay-per-call hosted APIs — your choice

Contact

Share the target app (River: Buy Bitcoin), your concrete use case (e.g. "nightly statement export for tax"), any sandbox credentials you already hold, and the deadline that matters. We reply within one business day with scope, price, and a proposed milestone plan.

Open the contact page →

Preferred engagement language: English. Time zones: we cover US, EU, and APAC working hours.

Engagement workflow

1. Scope confirmation: integration goals and API surfaces (login, balances, statements, Lightning, recurring buys).
2. Protocol analysis and API design (2–5 business days, complexity-dependent).
3. Build and internal validation with contract tests (3–8 business days).
4. Docs, samples, and test plan delivery (1–2 business days).
5. Typical first delivery: 5–15 business days; third-party approvals may extend timelines.

FAQ

What do you need from me?

How long does delivery take?

How do you handle compliance?

Do you bypass 2FA or Proof-of-Reserves?