v33

latestOpenAPI 3.1.0Proprietaryraw.githubusercontent.com2026-05-28103497709.6 KB

Cross-Currency Transfers

Create a transfer quote

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

Transfer Types Supported:

Account to Account: Transfer between internal/external accounts with 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

Important: If you are transferring funds in the same currency (no exchange required), use the /transfer-in or /transfer-out endpoints instead.

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

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

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": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "destination": {
    "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "paymentRail": "ACH"
  },
  "lockedCurrencyAmount": 1000,
  "description": "Invoice #1234 payment",
  "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' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED' required

Current status of the quote

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.

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": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "destination": {
    "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,
  "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
  }
}