Arculus Wallet API integration (cold storage OpenData)

Deliverables checklist

• OpenAPI 3.1 specification covering address registration, balance polling, transaction export and NFT listing
• Protocol report: how the Arculus app derives xpubs, paginates Etherscan/BscScan/Mempool calls, and brokers WalletConnect handshakes
• Runnable Python (FastAPI) and Node.js (Express) reference servers — Docker images included
• Postman collection plus pytest / vitest integration tests against testnet and mainnet
• Compliance brief: MiCA, FATF Travel Rule thresholds, GDPR data-retention guidance

Feature module — balance & portfolio

A normalized balance endpoint that fans out across each blockchain bound to a user's Arculus Key Card (BTC UTXO scan, ETH/EVM eth_getBalance + ERC-20 balanceOf, Solana getTokenAccountsByOwner, Cardano UTxO) and returns a single JSON object with fiat valuations from Chainlink and CoinGecko feeds. Use for treasury dashboards or pre-trade risk checks.

Feature module — transaction history

Paginated transaction export with filters by chain, asset, direction (in / out / self), counterparty address, and date range. Each row includes block height, timestamp, tx hash, gas / fee, USD value at execution time and a deterministic counterparty label when known. Powers reconciliation, Form 8949 filings, and AML monitoring.

Feature module — NFT inventory

Ethereum (ERC-721 / ERC-1155) and Polygon NFT enumeration with metadata resolution, floor-price lookup, and OpenSea / SuperRare collection mapping. Returns a single inventory document per Arculus address that downstream gallery, insurance, or proof-of-ownership systems can consume.

Feature module — WalletConnect bridge

Server-side WalletConnect v2 session manager that mirrors what the Arculus app does locally: receive a DApp pairing URI, surface the approval scope, route signing requests back to the user's mobile app, and persist an audit trail of every approved eth_sendTransaction and personal_sign event.

Feature module — staking & rewards

Read-only staking positions and reward accruals for Cardano (ADA), Solana (SOL) and Cosmos (ATOM) addresses. Useful for tax engines that need to classify staking income separately from capital-gains events, and for back-office tools that monitor delegation health and slashing risk.

1. Crypto tax engine sync

Context: An accounting firm onboards a client who holds long-term BTC, ETH and ADA on Arculus. Data & APIs: address registration endpoint, paginated /transactions with cost-basis-friendly fields, and a CSV export endpoint compatible with Koinly and CoinTracking. OpenData mapping: follows the same shape as Open Banking statement endpoints — date, amount, currency, counterparty, reference — but with on-chain primitives substituted for IBANs.

2. DeFi position monitoring

Context: A family office wants real-time visibility into Aave, Uniswap and Lido positions opened from an Arculus card via WalletConnect. Data & APIs: WalletConnect session log, plus an enriched /positions endpoint that resolves LP tokens, debt positions and yield accruals. OpenData mapping: parallels OpenBanking "product holdings" endpoints — each open DeFi position becomes a structured holding row.

3. NFT collateral valuation

Context: A lender accepts blue-chip NFTs as collateral. Data & APIs: NFT inventory endpoint per Arculus address, floor-price feed, and a verification endpoint that issues a fresh signed challenge through the Arculus Auth SDK to prove current control. OpenData mapping: behaves like an asset-verification rail in OpenFinance — proof of ownership delivered through a cryptographic signature instead of a bank-confirmed statement.

4. Compliance & Travel Rule attribution

Context: A licensed CASP must attach originator data to outbound transfers above EUR 1,000 under MiCA. Data & APIs: outbound transaction webhook, IVMS-101 originator payload builder, and an unhosted-wallet attestation flow that proves a customer controls their Arculus card. OpenData mapping: aligns with FATF Recommendation 16 messaging and EU Transfer of Funds Regulation requirements.

5. Passwordless enterprise login

Context: An exchange wants its institutional users to authenticate with the same Arculus Key Card they use for self-custody. Data & APIs: integration of the Arculus Auth SDK (FIDO2 / WebAuthn) for passwordless login and transactional authorization, plus an audit-trail export endpoint. OpenData mapping: brings strong-customer-authentication signals into the OpenFinance access-control plane.

Auth: proof-of-control challenge

POST /api/v1/arculus/auth/challenge
Content-Type: application/json

{
  "address": "0x9a8f...e21d",
  "chain": "ethereum",
  "client_id": "of-lab-acct-019"
}

200 OK
{
  "challenge": "Sign-in to OpenFinance Lab at 2026-05-11T10:02:11Z nonce=8c1f...",
  "expires_in": 300
}

# The user taps their Arculus Key Card; the signed message is returned:
POST /api/v1/arculus/auth/verify
{
  "address": "0x9a8f...e21d",
  "signature": "0x7c...91",
  "challenge_id": "ch_01HXY..."
}

200 OK
{ "access_token": "eyJhbGciOi...", "expires_in": 3600 }

Statement export — transactions

POST /api/v1/arculus/transactions
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "addresses": ["bc1q...", "0x9a8f...e21d", "addr1q..."],
  "from_date": "2026-01-01",
  "to_date":   "2026-05-11",
  "chains":    ["bitcoin", "ethereum", "cardano"],
  "format":    "json"
}

200 OK
{
  "page": 1, "page_size": 100, "total": 247,
  "items": [
    {
      "tx_hash": "0x52a...c11",
      "chain": "ethereum",
      "timestamp": "2026-04-12T08:11:42Z",
      "direction": "out",
      "asset": "USDC",
      "amount": "1500.00",
      "fee": "0.00214",
      "usd_value_at_tx": 1500.00,
      "counterparty": "0xUNI...router"
    }
  ]
}

Webhook — WalletConnect signing event

POST https://your-callback.example.com/webhooks/arculus
X-Arculus-Signature: t=1747000000,v1=4d2a...
Content-Type: application/json

{
  "event": "walletconnect.request.approved",
  "session_id": "wc_01HXZ...",
  "dapp": { "name": "Uniswap", "url": "https://app.uniswap.org" },
  "method": "eth_sendTransaction",
  "chain": "ethereum",
  "address": "0x9a8f...e21d",
  "tx_hash": "0x91b...004",
  "approved_at": "2026-05-11T09:55:08Z"
}

# Error envelope is consistent across endpoints:
{
  "error": {
    "code": "rate_limited",
    "message": "Indexer backoff; retry in 12s",
    "retry_after": 12
  }
}

Regulatory alignment

Self-custody integrations sit inside a fast-moving regulatory perimeter. We design every Arculus build around MiCA (in full force across the EU since 30 December 2024), the EU Transfer of Funds Regulation and the FATF Travel Rule. For transfers to or from unhosted wallets above EUR 1,000, attestation of control through a card-signed message is wired in by default. US deployments add FinCEN-style record-keeping; UK deployments map to the FCA cryptoasset financial-promotions regime.

Data minimisation & consent

Private keys never leave the Arculus Key Card. Our APIs only ever request public addresses, signed challenges and explicit user consent for each scope (read balances, read transactions, broker DApp sessions). Consent records, request logs, IP and user-agent metadata are kept for the retention window your jurisdiction requires (e.g. five years in the EU under AMLD), then purged via a documented job.

Security posture

The Arculus Key Card is CC EAL6+ certified — among the highest assurance levels for commercial secure elements. We complement that with mTLS between services, signed webhooks (HMAC-SHA256), short-lived access tokens, IP allowlisting per tenant, and an annual external review of the protocol-analysis report.

About our studio

OpenFinance Lab is an independent engineering studio focused on app protocol analysis and OpenData / OpenFinance / OpenBanking integrations. Our team blends backgrounds in fintech engineering, mobile reverse engineering, blockchain indexing and regulatory advisory. We have shipped production integrations across exchanges, custodians, neobanks, retail payments and self-custody wallets.

• Fintech, custodial & non-custodial wallets, exchanges, payments
• Mobile protocol analysis for Android & iOS, with FIDO2 / WebAuthn experience
• Python, Node.js, Go and Rust reference SDKs plus full test harnesses
• End-to-end delivery: scope → analysis → build → validation → compliance
• Source code delivery from $300 — runnable API source code and full documentation; pay after delivery upon satisfaction
• Pay-per-call API billing — access our hosted endpoints and pay only per call; no upfront cost

Contact

Send us the target app, the data scope you need (balances, transactions, NFTs, WalletConnect events) and any existing sandbox or developer-platform credentials. We will reply with a fixed-price quote and a delivery timeline.

Contact page

Engagement workflow

1. Scope confirmation: which Arculus data (balance, transactions, NFTs, WalletConnect, staking) and which downstream consumers.
2. Protocol analysis & API design (2–5 business days) — including address derivation, indexer choice and Auth SDK scope.
3. Build & internal validation (3–8 business days) across mainnet and at least one testnet per chain.
4. Docs, samples, Postman, and integration tests (1–2 business days).
5. Typical first delivery: 5–15 business days; multi-chain or compliance-heavy stacks may extend.

FAQ

Does Arculus Wallet expose an official public API for balances and transactions?

How long does an Arculus Wallet integration take?

How is compliance handled for self-custody wallets like Arculus?

Can the integration sync with tax tools like Koinly or CoinTracking?