Sign in
Cross-Currency Transfers

Create a transfer quote

Generate a quote for a transfer between any combination of accounts and UMA addresses. This endpoint handles same-currency and cross-currency transfers alike, and provides the necessary instructions to execute the transfer.

Transfer Types Supported:

  • Account to Account: Transfer between internal/external accounts, with or without currency exchange.
  • Account to UMA: Transfer from an internal account to an UMA address.
  • UMA to Account or UMA to UMA: This transfer type will only be funded by payment instructions, not from an internal account.

Key Features:

  • Flexible Amount Locking: Always specify whether you want to lock the sending amount or receiving amount
  • Currency Exchange: Handles all cross-currency transfers with real-time exchange rates
  • Payment Instructions: For UMA or customer ID sources, provides banking details needed for execution

Same-currency transfers: Use this endpoint for same-currency transfers too. Set immediatelyExecute: true to create and execute in a single request. The older /transfer-in and /transfer-out endpoints are deprecated.

Requires a token with the TRANSACT permission; VIEW alone is not sufficient. A quote is the instrument a later execute draws on, and immediatelyExecute moves funds within this same request.

post/quotes

Headers

Idempotency-Keystring
Example:<uuid>

A unique identifier for the request. If the same key is sent multiple times, the server will return the same response as the first request.

Request body

lookupIdstring

Lookup ID from a previous receiver lookup request. If provided, this can make the quote creation more efficient by reusing cached lookup data. NOTE: This is required for UMA destinations due to counterparty institution requirements. See senderCustomerInfo for more information.

lockedCurrencySide'SENDING' | 'RECEIVING' required

The side of the quote which should be locked and specified in the lockedCurrencyAmount. For example, if I want to send exactly $5 MXN from my wallet, I would set this to "sending", and the lockedCurrencyAmount to 500 (in cents). If I want the receiver to receive exactly $10 USD, I would set this to "receiving" and the lockedCurrencyAmount to 10000 (in cents).

lockedCurrencyAmountinteger required

The amount to send/receive in the smallest unit of the locked currency (eg. cents). See lockedCurrencySide for more information.

immediatelyExecuteboolean

Whether to immediately execute the quote after creation. If true, the quote will be executed and the transaction will be created at the current exchange rate. It should only be used if you don't want to lock and view rate details before executing the quote. If you are executing a pre-existing quote, use the /quotes/{quoteId}/execute endpoint instead. This is false by default. This can only be used for quotes with a source which is either an internal account, or has direct pull functionality (e.g. ACH pull with an external account). Not supported when the source is an internal account of type EMBEDDED_WALLET: those transfers require a Grid-Wallet-Signature over the payloadToSign returned in the quote response, which is not available in a combined create-and-execute call. Create the quote first with immediatelyExecute: false and then call POST /quotes/{quoteId}/execute with the Grid-Wallet-Signature stamp header.

descriptionstring

Optional description/memo for the transfer

remittanceInformationstring

Free-form information about the payment that travels with it to the recipient. The field this populates depends on the payment rail: for ACH it populates the Addenda record, for FedNow and RTP it populates the remittanceInformation field, and for wires it populates the OBI (Originator to Beneficiary Information) / beneficiary information.

purposeOfPayment'GIFT' | 'SELF' | 'GOODS_OR_SERVICES' | 'EDUCATION' | 'HEALTH_OR_MEDICAL' | 'REAL_ESTATE_PURCHASE' | 'TAX_PAYMENT' | 'LOAN_PAYMENT' | 'UTILITY_BILL' | 'DONATION' | 'TRAVEL' | 'FAMILY_SUPPORT' | 'SALARY_PAYMENT' | 'OTHER'

The purpose of the payment. This may be required when sending to certain geographies (e.g. India).

scaFactor'SMS_OTP' | 'TOTP' | 'PASSKEY'

A Strong Customer Authentication factor.

FactorDescription
SMS_OTPOne-time code sent by SMS to the customer's verified phone. Requires no prior enrollment.
TOTPTime-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking).
PASSKEYWebAuthn passkey assertion. Requires enrollment.
senderCustomerInfoobject

Key-value pairs of additional information about the sender which was requested by the destination. This is relevant when the destination requires more sender info than was provided during customer creation. Any fields specified in requiredPayerDataFields from the response of the /receiver/uma/{receiverUmaAddress} (lookupUma) or /receiver/external-account/{accountId} (lookupExternalAccount) endpoints MUST be provided here if they were requested. If the destination did not request any additional information, this field can be omitted.

Example request

{
  "lookupId": "Lookup:019542f5-b3e7-1d02-0000-000000000009",
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "paymentRail": "ACH"
  },
  "lockedCurrencyAmount": 1000,
  "description": "Invoice #1234 payment",
  "remittanceInformation": "12345",
  "platformFeeOverride": {
    "platformFixedFee": {
      "amount": 50,
      "currency": "USD"
    },
    "platformVariableFeeBps": 30
  },
  "senderCustomerInfo": {
    "FULL_NAME": "Jane Receiver",
    "NATIONALITY": "FR"
  }
}

Response

Transfer quote created successfully. The response includes exchange rates, fees, and transfer details. For transfers involving UMA addresses, payment instructions are also included for execution through banking systems.

idstring required

Unique identifier for this quote

status'PENDING' | 'PENDING_AUTHORIZATION' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED' required

Current status of the quote. PENDING_AUTHORIZATION occurs only for customers in a region where Strong Customer Authentication is required (e.g. EU): the quote carries an scaChallenge that must be authorized before execution, and for realtime-funding sources paymentInstructions are withheld until it is satisfied.

createdAtstring date-time required

When this quote was created

expiresAtstring date-time required

Absolute UTC timestamp when the rate locked in this quote becomes invalid and the quote can no longer be executed. The window depends on the rail and corridor: instant rails (Lightning, Spark, USDC on Solana/Base/Polygon, RTP, SEPA Instant) typically expire in 1–5 minutes; corridors with longer settlement guarantees may have longer windows. Always rely on this timestamp rather than assuming a fixed window.

totalSendingAmountinteger required

The total amount that will be sent in the smallest unit of the sending currency (eg. cents).

totalReceivingAmountinteger required

The total amount that will be received in the smallest unit of the receiving currency (eg. cents).

exchangeRatenumber required

Number of sending currency units per receiving currency unit.

feesIncludedinteger required

The fees associated with the quote in the smallest unit of the sending currency (eg. cents). Note: this value may fluctuate between quotes — some underlying fee components are defined in the receiving currency, so their equivalent in the sending currency moves with the FX rate. The fees shown here are locked only for the lifetime of this quote.

platformFeesIncludedinteger

The portion of feesIncluded collected by the platform (platform-configured transaction fees), in the smallest unit of the sending currency. 0 when the platform has no applicable fee configured. Already included in feesIncluded. May be omitted from payloads produced before platform fees existed.

paymentInstructionsPaymentInstructions[] — unresolved $ref

Payment instructions for executing the payment. This is not required when using an internal account source.

transactionIdstring required

The ID of the transaction created from this quote.

counterpartyInformationCounterpartyInformation

Additional information about the counterparty, if available and relevant to the transaction and platform.

Example response

{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T12:00:00Z",
  "expiresAt": "2025-10-03T12:05:00Z",
  "source": {
    "sourceType": "ACCOUNT",
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "paymentRail": "ACH"
  },
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "receivingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "totalSendingAmount": 123010,
  "totalReceivingAmount": 1000,
  "feesIncluded": 10,
  "platformFeesIncluded": 5,
  "paymentInstructions": [
    {
      "accountOrWalletInfo": {
        "accountType": "USD_ACCOUNT",
        "paymentRails": [
          "ACH",
          "WIRE"
        ],
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "bankName": "Chase Bank",
        "reference": "UMA-Q12345-REF"
      },
      "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
    },
    {
      "accountOrWalletInfo": {
        "accountType": "SPARK_WALLET",
        "assetType": "BTC",
        "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
        "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
      }
    }
  ],
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
  "counterpartyInformation": {
    "FULL_NAME": "John Sender",
    "BIRTH_DATE": "1985-06-15",
    "NATIONALITY": "DE"
  },
  "rateDetails": {
    "counterpartyMultiplier": 1.08,
    "counterpartyFixedFee": 10,
    "gridApiMultiplier": 0.925,
    "gridApiFixedFee": 10,
    "gridApiVariableFeeRate": 0.003,
    "gridApiVariableFeeAmount": 30
  },
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  }
}

Changes