Complete credit lifecycle

An institutional Earn integration should not end at deposit, yield, and redemption. It should keep the customer informed if credit deteriorates, explain what happened to the original position, show the recovery path, and—when a separate opportunity is actually open and the wallet is eligible—let the customer review a Distressed Recovery Fund as a new investment decision.

This guide is the shared lifecycle contract for every Torq use case. The audience playbooks explain who owns each service, signer, ledger, and customer surface.

Developer Preview. Public recovery reads and documentation are available for integration design. Credentials, wallet sessions, server GraphQL, approved packages, and investor fund-action execution remain controlled Preview capabilities. Never replace an unavailable capability with a caller-supplied contract call.

The whole customer journey

Two positions, two decisions

The original vault position and a Distressed Recovery Fund position are economically and operationally separate:

An affected position does not automatically make a wallet eligible for a recovery fund, subscribe the wallet, compensate a loss, or create a fund claim. Distressed-fund participation is a separate capital allocation with different risks and requires explicit customer approval.

Build the lifecycle data service

Use the dependency-free reference in examples/developer-platform/earn-program-reference/src/credit-lifecycle.mjs. Keep browser-safe wallet reads and secret-key server reads separate:

const lifecycle = await loadCreditLifecycle(walletApi, {
  serverApi, // server secret only; never bundle it into the client
  walletAddress,
  vaultId,
  fundId: selectedFundId,
});

renderOriginalVaultExposure(lifecycle.originalVaultExposure);
renderOptionalFundExposure(lifecycle.optionalFundExposure);

The loader uses these exact operations:

Do not infer that one resource belongs to another from matching names or timing. Preserve the canonical vault, market, position, fund, epoch, side-pocket, wallet, chain, block, and transaction identifiers returned by Torq. When a direct relationship is unavailable, label it unconfirmed.

Detect impairment without alarming customers incorrectly

1. Maintain a durable cursor for GET /v1/events or signed webhooks.
2. On any relevant vault, market, position, liquidation, loss, recovery, or fund event, reread the affected canonical resources.
3. Compare identifiers and freshness evidence; do not classify a position from an event name alone.
4. Show a plain-language state such as monitoring, redemption constrained, loss recorded, recovery active, or claimable only when the current schema supports it.
5. Keep deposits and other risk-increasing actions disabled when required evidence is stale, missing, blocked, or contradictory.

APY movement, a failed RPC request, a pending transaction, or a third-party alert is not proof that a Torq position is impaired.

Present the distressed-fund decision

Only present a subscribe action after all of these checks pass:

1. The selected fund exists and its freshness.status is current.
2. subscriptionStatus is open.
3. The wallet-specific canonical eligibility status is eligible.
4. The amount is a positive base-unit integer within the current minimum and maximum.
5. The customer has reviewed the quote asset, epoch, capacity, idle-redemption rules, acquisition exposure, side-pocket behavior, fees, pauses, claim paths, and lack of guaranteed recovery.
6. The customer explicitly approves this new allocation independently of the original vault action.
7. The current application has an approved Preview execution capability.

const proposal = buildDistressedFundDecisionReview({
  fund: selectedFund,
  amount: subscriptionAssets,
  explicitlyApproved: customerApprovedSeparateAllocation,
});

if (proposal.executionAvailability !== 'requires_approved_preview_capability') {
  throw new Error('Unexpected recovery-fund execution boundary');
}

Current execution boundary

The current external typed workflow catalog does not export investor fund subscription, idle redemption, or claim execution. Those actions exist in Torq's investor product, but an external integration must use only the exact executor and package supplied for its approved Developer Preview application.

If that capability is absent:

• keep the recovery center and canonical monitoring experience available;
• show the specific action as unavailable with capability_not_ready;
• provide the Preview access and support route;
• never synthesize target or calldata;
• never copy internal action identifiers into a public client and call them public SDK methods;
• never turn an event, receipt, or raw contract result into customer-visible completion.

This fail-closed boundary is intentionally explicit. It tells an integration exactly what can be built today and prevents an incomplete recovery write path from being disguised as production support.

Reconcile recovery safely

Keep a durable record keyed by customer, wallet, original vault position, optional fund position, fund epoch, side pocket, request, and transaction. Reconciliation should answer these questions independently:

1. What is the canonical state of the original vault position and any redemption claim?
2. What recovery cash, loss, or claim state is visible for the originating vault path?
3. Did the customer separately subscribe to a recovery fund?
4. How much fund capital remains idle, committed, claimable in quote, or claimable in kind?
5. Are claims paused, expired, already claimed, or still awaiting canonical projection?
6. Do the event cursor, current resource rows, and customer ledger agree?

For typed Torq workflows, require transaction and workflow final_success, then reread the affected resource. For an approved fund-action executor, follow its documented canonical completion rule and reread the fund investor status before posting any customer balance.

Test the complete journey

Run the reference tests, then exercise these scenarios on the approved Sepolia environment:

• eligible and ineligible wallets;
• Single Share, Senior, and Junior product presentation where configured;
• deposit success, rejection, replacement, duplicate registration, and reorg;
• current yield and liquidity changes without impairment;
• immediate and queued redemption states;
• stale or contradictory recovery evidence;
• an affected position with no available recovery fund;
• a relevant fund that is closed, full, paused, stale, or wallet-ineligible;
• explicit decline of the separate fund allocation;
• fund action requested while the Preview capability is absent;
• approved subscription, idle redemption, quote proceeds, and in-kind claim where the supplied Preview executor supports them;
• reload and cross-device resume from the durable event cursor;
• final reconciliation of the original vault path and the separate fund path.

Ship checklist

• The product explains the complete lifecycle before the first deposit.
• The original vault exposure and optional fund exposure use separate records and approvals.
• No alert, ranking, AI output, event, or APY movement invents an impairment state.
• The customer sees exact terms, risks, signer, network, amount, and availability before action.
• Missing fund eligibility or execution capability fails closed with a stable reason.
• Recovery-fund participation is never described as automatic compensation or guaranteed recovery.
• Every customer balance comes from canonical state, not a wallet receipt alone.
• The integration can resume every pending and recovery state after reload.

Continue with Wallet providers, Crypto lending protocols, Distressed recovery, and the API reference.