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.

Private Preview. Your application, customer population, signer model, scopes, products, and hosted environments require approval before live use.

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

1. Approved Torq organization, test and production applications, secret keys, webhook endpoint, and the exact vault, wrapper, partner, and workflow scopes required by the program.
2. Customer onboarding, disclosures, suitability, jurisdiction, complaints, and redemption policy.
3. Customer-level HSM or MPC authorization with network, target, amount, and action controls.
4. Durable SQL inbox, double-entry ledger, reconciliation worker, alerting, and support tooling.
5. 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.mjs

Map 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 balances

Complete 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_success plus 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.
• Private Preview 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.