Transfers/Initiate transfer
Initiate a transfer
Move money between accounts on the rails. Every transfer is two-phase: a hold is placed on the deterministic ledger, then settled with a guarded confirm that re-checks freezes — or voided if the rail rejects. Frozen accounts never move money. Amounts are integers in minor units; nothing is floating-point.
POST
https://api.griprails.com/v1/transfers
Body parameters#
fromCvustringrequired
The originating account's CVU. Resolved to a customer; an unknown CVU returns CUSTOMER_NOT_FOUND.
amountMinorinteger (bigint)required
Amount in the currency's minor units. 18450 = ARS 184.50. Never a float — the ledger is integer-only.
currencystringrequired
Account currency. ARS · USD. Must match the resolved account, or the call returns CURRENCY_MISMATCH.
destinationobjectrequired
The recipient — a CVU/CBU/alias. Routed to the clearing account for the tenant and currency.
idempotencyKeystringrequired
Deterministic transfer id derivation (Inv-11). Retries with the same key return the original hold — never a duplicate.
metadataobjectoptional
Your own key-value data, returned verbatim on the transfer and its forensic record.
Product modules#
Ten modules sit on one ledger and one signed catalog. All ship the production-path *Guarded variant, sealed across three red-team rounds:
cvuAccount issuanceARS
cbuAccount issuanceUSD
transfer2-phase hold · confirmGuardedAR
debinPull · single-use authorizationAR
qrQR pay · CRC ≠ authAR
yieldGuarded source · accrual—
brokerageGuarded sell settlement—
restrictionsEmbargo · freeze-firstAR
Two-phase & fail-closed
Settlement truth lives in the ledger. initiate places a hold; confirmGuarded re-checks the freeze state before settling; cancel voids the hold. A frozen or embargoed account stops here — money never moves. Holds auto-void on timeout.
Returns#
A Result — ok with the initiated transfer (status held), or err with a typed code (CUSTOMER_NOT_FOUND, CURRENCY_MISMATCH, ACCOUNT_FROZEN, NO_CLEARING). Settle with /confirm; the ledger is the single source of balance.