Neobanks
Add institutional-grade Earn to a neobank without making RPC, transaction receipts, or webhook payloads your books and records. Torq supplies canonical product and workflow state; your product owns onboarding, policy, custody, disclosures, customer accounting, and support.
controlled distribution. Your application, customer population, signer model, scopes, products, and hosted environments require approval before live use.
Neobank Earn
Customer ledger, controlled signing, and daily reconciliation
Apply product policy, eligibility, and customer disclosures.
Bind the customer request to server and signer policy.
HSM or MPC submits only the prepared Torq transaction.
Credit the customer ledger only after final_success.
Earn catalog, balances, activity, and redemption state.
Suitability, limits, approvals, and disclosures.
Customer-owned HSM or MPC authorization boundary.
Durable inbox and canonical position reconciliation.
What you will build
- Approved Earn catalog and suitability policy for eligible customers.
- Detailed vault product page, projected yield inputs, allocations, liquidity, fees, and activity.
- Deposit and redemption instructions authorized by a customer-owned HSM or MPC policy.
- Double-entry customer subledger that posts only from canonical Torq completion.
- Durable event inbox, reconciliation jobs, operations queue, and customer-safe failure states.
The customer-owned signer remains outside Torq. The secret key authenticates your server to Torq; it does not authorize arbitrary custody movement or supersede the customer's consent policy.
Prerequisites
- Approved Torq organization, test and production applications, secret keys, webhook endpoint, and the exact vault, wrapper, partner, and workflow scopes required by the program.
- Customer onboarding, disclosures, suitability, jurisdiction, complaints, and redemption policy.
- Customer-level HSM or MPC authorization with network, target, amount, and action controls.
- Durable SQL inbox, double-entry ledger, reconciliation worker, alerting, and support tooling.
- Separate keys, databases, queues, and environment configuration for test and production.
Project files
Use examples/developer-platform/earn-program-reference as the executable Torq boundary:
src/torq-api.mjs # secret-key requests and stable errors
src/catalog.mjs # deep product and customer-resource reads
src/workflows.mjs # proposal -> prepare -> signer -> final_success
src/webhooks.mjs # exact raw-body HMAC verification
test/reference.test.mjsMap it into your services:
services/earn/catalog/ # allowed product universe and disclosures
services/earn/instructions/ # idempotent customer deposit/redeem orders
services/earn/signer-adapter/ # HSM or MPC policy and transaction submission
services/earn/torq-workflows/ # prepare/register/wait state machine
services/earn/event-inbox/ # durable, deduplicated signed deliveries
services/earn/ledger/ # pending and finalized journal entries
services/earn/reconciliation/ # positions vs customer and omnibus balancesComplete data contract
Complete credit lifecycle
Implement the complete credit lifecycle as two customer subledgers under one Earn account:
Add src/credit-lifecycle.mjs to the server-side Torq adapter and persist the vault, fund, epoch,
side-pocket, wallet, request, transaction, and freshness identifiers used for every posting.
Build the integration
1. Provision environment and authority boundaries
Create one Torq application per environment. Store the secret key and webhook secret in a server secret manager, restrict egress to the Torq API, and give each service only its required scopes. Persist Torq application, environment, chain, customer, account, and request IDs on every instruction.
2. Create the governed product universe
Load complete catalog and detail resources through src/catalog.mjs. Apply your approved-product,
customer, jurisdiction, concentration, liquidity, and disclosure policies to canonical fields. Store
Torq resource IDs, not copied names, as references. Refresh before every proposal and fail closed on
stale or unavailable state.
3. Design the customer and ledger model
Use an immutable instruction ID and stable idempotency key per customer action. Create separate pending, submitted, finalized, failed, and reversed journal states. Torq positions are canonical protocol state; your subledger is the customer's financial record and must reconcile to the declared custody structure. Never mark yield or principal available from an estimated response.
4. Evaluate eligibility and suitability
Read GET /v1/eligibility, current positions, share mobility, product detail, liquidity, and fees.
Combine Torq eligibility with your own policy. Keep the reason sources distinct so operations can
tell whether Torq, customer policy, custody, or your program blocked the action.
5. Obtain customer authorization
Show the product, principal, fees, wrapper, risks, redemption behavior, signer account, and network.
Record explicit customer authorization for role.investor.partnerWrapperDeposit or
role.investor.partnerWrapperRedeem. Do not reuse a general terms acceptance as transaction consent.
6. Prepare the exact workflow
Call POST /v1/workflows/prepare from the server with the typed request and idempotency key. Require
preflight passed; persist request ID, snapshot, expiry, expected intent set, and blocked reasons.
Present the exact transaction plan to your signing policy.
7. Enforce HSM or MPC policy
The HSM or MPC adapter independently checks customer account, chain, target, calldata/value binding, amount limits, product allowlist, expiry, transaction ordering, and approval evidence. Simulate when required. The customer-owned signer submits only the prepared intent and returns the transaction hash.
8. Register, finalize, and post the ledger
Use POST /v1/workflows/{requestId}/transactions for every submitted transaction. Wait for the
transaction and GET /v1/workflows/{requestId} to reach final_success. Reread GET /v1/positions
and affected vault resources, then post the final journal. A chain receipt can move an instruction
to pending settlement, never to an available customer balance.
9. Process the durable event inbox
Verify timestamp, delivery ID, HMAC, and exact raw body with src/webhooks.mjs; insert once before
acknowledging. A worker rereads canonical resources, advances the order state idempotently, and emits
your internal ledger event. Retry failures and preserve request IDs without logging credentials or
wallet proofs.
10. Reconcile continuously
Reconcile customer subledgers, omnibus/onchain positions, pending instructions, fees, redemptions, and canonical Torq resources. Alert on unmatched final workflows, positions without ledger owners, ledger balances without positions, stale freshness, duplicate events, and unresolved failures.
Failure and recovery table
Production checklist
- Secret keys, webhook secrets, custody credentials, and customer PII are isolated by environment.
- Every product field and disclosure maps to a documented Torq canonical resource.
- Eligibility, freshness, product allowlist, and customer policy are reevaluated before signing.
- HSM or MPC verifies exact prepared chain, target, value, order, and expiry.
- Ledger credit requires transaction and workflow
final_successplus position reread. - Durable event inbox deduplicates delivery and event IDs before reconciliation.
- Daily totals reconcile positions, pending orders, fees, and customer journal balances.
- Timeout, reorg, stale state, repeated request, and redemption tests pass on Sepolia.
- controlled distribution disclosures and operational ownership are approved.
Run node --test examples/developer-platform/earn-program-reference/test/*.test.mjs, then continue
with authentication, canonical state,
and events.