These routes follow credits the bank reports to the reserve account: list and read them, resolve parked credits, approve credits before minting, configure screening, and process recalls. All relative paths sit under /api/v2/bank-rail. See Bank rail API for connections, token links, and clients.
Follow and resolve credits
GET /connections/ lists reported credits newest first, and GET /connections/ reads one. A matched credit mints once to the client. Unmatched credits or credits blocked by token compliance mint to the rail wallet as suspense. Credits that cannot complete are parked with an operations case.
Send resolution actions to POST /connections/:
When the bank-rail approval family is on, allocate and return-to-payer move the credit to awaiting-checker. Another manager decides via POST /connections/ with {"action": "approve", "approval or "reject". Refusals return 409 bank with data.reason (such as proposer-cannot-approve or approver-).
When the approval family is off, resolution starts immediately. Approving transfers or burns tokens once (plain transfer and supply-delegate burn in delegate mode), while rejecting leaves the credit parked.
Switch a client to gateway delivery
Client links deliver to the client's wallet until two bank rail managers switch them. The link's delivery object holds target (wallet or gateway), any open request, lastCheck, and rowVersion.
POST /connections/checks gateway readiness without saving anything, returning{connection Id}/ client- links/ {client Link Id}/ delivery- checks ready,gateway,receiptToken, per-checkpassed/detail/fix, anddepositFee(or retryable503if unreadable).POST /connections/with{connection Id}/ client- links/ {client Link Id}/ transitions {"transition": "enable-validates the gateway and opens a maker-checker request (gateway- delivery", "row Version": 3} preconditions-failed,booked-mode,delivery-request-open, orrow-versionon refusal).POST /connections/with{connection Id}/ client- links/ {client Link Id}/ decisions {"decision": "approve", "approvalorId": "... "} "reject"decides the request (same-actorif proposer decides). Approval rechecks the gateway: failing rechecks withdraw the request withdelivery-staleand a warning case. Undecided requests expire after seven days.{"transition": "disable-immediately reverts future credits to wallet delivery and withdraws any open request.gateway- delivery", "row Version": 4}
Credits for a custody gateway client
A gateway-targeted credit mints to the rail wallet after prechecking the gateway, returning minted with a delivery object. Failing checks park the credit as delivery-blocked before minting (unreadable gateways keep the credit admitted for the next pass):
fee-account-unset: a coin with a deposit fee lacks a non-gateway fee account. Set one as custody gateway admin.fee-account-blocked: the fee account fails the coin's compliance rules. Clear it as compliance officer.
Fix the gateway or switch back to wallet delivery, then send {"action": "retry"}. Each credit keeps the target chosen when its mint was prepared, so switching back to wallet delivery affects only unminted credits.
For wallet-delivered credits, delivery is null. For gateway credits, delivery carries gateway, receiptToken, lastCheck, and state: null while submitting the mint, then minted-undelivered with amount in base units. Undelivered coins count as inTransit (not suspense) and cannot be allocated, returned to payer, or recalled mid-send.
After rechecking the gateway, the rail transfers coins to it: state moves through sending to sent-unreported (carrying transactionHash and logIndex). Unreadable or paused gateways defer the send under a screening-outage case without spending an attempt. Other failures set state to send-failed with a critical case.
Send {"action": "retry"} on a send-failed credit to try again. The rail checks whether the previous transfer landed first so nothing sends twice. Refused retries return 409 RETRY_ with data.reason:
delivery-in-flight: the previous transfer may still land.recall-open: a bank recall is open on the credit.returned-elsewhere: the gateway returned coins to a wallet other than the current rail wallet.delivery-not-retryable: the current delivery state cannot be retried.
A client suspended in the organisation
The rail sends nothing to a client whose participant account is suspended, closed or terminated in the credit's organisation. The same account in another organisation does not hold the credit.
- Before the mint, the credit parks as
client-suspendedwith nothing minted, and a warning case names the wallet and its status. This covers wallet and gateway delivery alike, and a client whose wallet the token also blocks. A credit that matched no client still mints to the rail wallet as suspense. - A gateway credit that minted before the suspension is not sent. Its
delivery.statereadssend-failed, and the case names the status. { "action": "retry" }runs the credit again once the account is active again, and parks it again while it is not.{ "action": "return-closes the unminted credit under the bank's refund reference.to- payer" } - An
allocateto such a client is refused with403RECIPIENT_SUSPENDED(DALP-190196), both when it is requested and when it is approved. An allocation approved before the suspension does not start: the credit parks again under a new case. The suspense stays in the rail wallet.
Where the coins are
The rail tracks sent credits against gateway deposits by (transaction and depositId, populating gatewayStage, gatewayStages, and on settlement receiptsMinted, fee, and receiptRecipient (matching custody.):
Failed gateway reads leave state unchanged and open no case.
Approve a credit before it mints
When creditCheckerThreshold is set on the token link, the rail sums the client's credits over the past 24 hours before minting (unmatched credits are evaluated alone). While the bank-rail approval family is on, credits exceeding the threshold wait in awaiting-mint-approval with mintApproval (approvalId and 7-day expiry).
- Approve: Send
{"action": "approve", "approvalto the credit's decisions route (any bank rail manager can decide since the bank opened it). Completed wallet rotations invalidate unminted approvals so they re-evaluate. Credits under recall cannot be approved.Id": "... "} - Reject: Moves the credit (or expired approval) to
mint-unapprovedwith a critical case.retryre-requests approval with you as maker, orreturn-to-payercloses it without a transaction. - Reconciliation: Credits awaiting mint approval appear in
pendingInasawaitingApprovaland are never overdue.
Update the threshold via POST /connections/ with {"transition": "update-. Setting or lowering applies immediately. Raising or removing (null) opens mintLimitRequest for another manager to decide via POST /connections/ (approve or reject, 7-day expiry). With the bank-rail family off, raises still need wallet verification on session calls and store a waived record. Concurrent changes return mint-limit-pending.
Delegate mint caps
A delegate link can pass expectedMintCap (token base units) at creation to cap rail wallet minting (booked links refuse it with mint-cap-booked). Update the cap later with {"transition": "update- from a token governor wallet (with wallet verification on session calls).
Re-delegation is an async transaction honouring Prefer: wait: returns 200 if settled, or 202 with mintCapReplacement (transactionId, previousMintCap) and Location pointing to GET /connections/. Reading the list (or running credits, reconciliation, or rotation readiness) settles mintCapReplacement, restoring previousMintCap on failure. Concurrent changes return state.
First, lower, or unchanged caps apply immediately (parking credits as supply-authority until indexed). Raises or removals (null) open mintLimitRequest, and the approving manager's wallet submits the re-delegation. Changes during wallet rotation return rail-wallet-contained. Links report outstandingMint beside expectedMintCap. Credits hitting the cap park as mint-cap until you raise the cap or tokens burn.
A mint the token refuses
Before submitting a mint, the rail checks token acceptance. Refusals keep the credit in minting for five minutes (allowing recent role or unpause updates to index), then park it with park, a critical case, and mintRefusal:
Once resolved, send {"action": "retry"} to re-run from admission.
Screen credits and cash-outs
Every confirmed deposit (including unmatched ones) and every cash-out prior to bank instruction is screened by the connection's AML provider. Results are stored on the credit (screening), on screening rows, and on an investor-linked case. Credit payer details from FIX tags 5001, 5002, and 5003 appear on payer.
Configure screening with GET and PUT /connections/:
List available providers via GET /connections/ (bank rail manager or auditor, returning 403 bank to others). Only active providers screen.
Failed checks park credits without minting:
payer-: add and approve the payer account under maker-checker, thenaccount- not- verified retry. Mint approval cannot bypass this check.aml-held/aml-rejected:retryopens a non-waivable maker-checker approval decided viaPOST /connections/. Held or rejected cash-outs move to{connection Id}/ credits/ {credit Id}/ decisions awaiting-checkerfor another manager to decide viaPOST /connections/.{connection Id}/ cash- outs/ {cash Out Id}/ decisions
List screening records via GET /connections/ with optional ISO date-time filter[from] and filter[to] (invalid bounds return 400 wire.).
Recalls
When a bank sends a FIX credit reversal (requires credit-reversal in allowedMessages.inbound via PATCH /connections/), the rail creates a received recall, blocks further minting or retries on that credit, and opens a critical case.
List and read recalls with GET /connections/ (filter[state]) and GET /connections/. Duplicate open recalls or over-reversals are refused with a critical case. Reversals arriving before their credit receive no reply so the bank resends once the credit lands.
Execute or abandon a recall
Recalls always require maker-checker via POST /connections/:
{"transition": "request-requests recovery matching the credit's state: cancel unminted credits, burn or book suspense, claw from a delegate client, book a correction on a booked client, or wait for a custody gateway return. Refused while minting,execution"} delivery-in-flight, park resolution, live cash-out, or wallet containment blocks it. Open recalls also refuse new cash-outs (recall-open).{"transition": "abandon", "reason": "...closes the recall without token recovery (leaving a reserve gap until adjusted)."}
A different manager decides via POST /connections/ (approve or reject with approvalId). If the credit moved before approval, approve returns recall-stale and resets to received with a case. Rejections and expiries also reset to received.
Clawing and burning a delegate or gateway recall
An approved delegate recall enters clawing. A token custodian force-transfers tokens from the client (or a gateway manager returns/recovers a gateway deposit) into the rail wallet, and a manager records each finalised transfer via POST /connections/:
{
"transition": "record-claw",
"transactionHash": "0x3f9c2a7e5b1d84c06e2a9f4b7d3c1e8a5f6b2d9c0e7a4f1b3c5d8e2a6f9b0c4d",
"logIndex": 0
}- Mismatched transfers (wrong timing, token, sender, or destination) return
claw-mismatch. Duplicates across recalls returnclaw-duplicate, and unfinalised blocks returnclaw-unfinalized. - Once recorded claws reach the recall amount, or when you send
{"transition": "close-, the recall moves toclaw"} burning. - The rail burns recovered units once, writes down any shortfall, completes the recall, and returns any excess to the client (retrying every five minutes under a warning case if blocked).
- A
bookedrecall books one correction from the client against the minting line directly.
Recall a delivered credit
A credit with delivery. minted receipts at the client's custody gateway. Because the rail cannot burn receipts directly, it claws receipts back into the rail wallet, redeems them through the rail wallet's own custody gateway, and burns the resulting coins (writing down gateway fees and any unrecovered balance).
Ensure the rail wallet has a registered identity, its own custody gateway, client link, and active approved payout address before requesting execution. Otherwise request-execution returns 409 DALP- (recall-gateway-missing). If receiptRecipient is not indexed yet, it returns delivery-in-flight.
Once approved (clawing), a receipt-token custodian force-transfers receipts from delivery. into the rail wallet and records each transfer with record-claw (or sends close-claw if receipts moved away).
In burning, the rail approves the gateway escrow, opens a redemption to the rail wallet, and tracks redemption (gateway, wallet, stage, requestId, receiptUnits, paidUnits). It claims automatically if auto-claim is off, burns the paid coins up to recorded receipts, and completes the recall.
If the gateway freezes, holds, rejects, or misdirects the redemption, redemption.stage reads failed with a critical case while staying burning. Once fixed on the gateway (or once rejected receipts return to the rail wallet, triggering a retry after five minutes), the recall resumes automatically.
A completed recall reads recalled with recoveredUnits, writtenDownUnits, and txHash, automatically creating a credit-recall reserve adjustment for any write-down. The credit reads recalled once cumulative recalls equal its full amount (recalledAmount otherwise).