Sign in
latestOpenAPI 3.1.0Proprietary2026-08-151526361.5 MB

27ff0fdca01c

Cross-Currency Transfers

Execute a quote

Execute a quote by its ID. This endpoint initiates the transfer between the source and destination accounts.

This endpoint 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).

When the quote's source is an internal account of type EMBEDDED_WALLET, the request must include a Grid-Wallet-Signature header. The header value is the full Grid wallet signature built over the payloadToSign value from the quote's paymentInstructions[].accountOrWalletInfo entry with the session private key of a verified authentication credential on the source Embedded Wallet.

Once executed, the quote cannot be cancelled and the transfer will be processed.

post/quotes/{quoteId}/execute

Path parameters

quoteIdstring required

The unique identifier of the quote to execute

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.

Grid-Wallet-Signaturestring

Full Grid wallet signature over the payloadToSign returned in the quote's paymentInstructions[].accountOrWalletInfo entry, produced with the session private key of a verified authentication credential on the source Embedded Wallet. Required when the quote's source is an internal account of type EMBEDDED_WALLET; ignored for other source types.

Request body

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.

Response

Quote processed. The outcome depends on whether SCA applies to the customer (currently EU customers):

  • No SCA required: the transfer is initiated and the quote status advances (PROCESSING / COMPLETED).

  • SCA required: the transfer is not initiated yet. The quote is returned with status PENDING_AUTHORIZATION and an scaChallenge; release the transfer by authorizing the quote you already hold — POST /quotes/{quoteId}/authorize (re-calling execute returns 409). A pre-funded send is a single challenge, so one authorization releases it. The challenge (and its SMS code / passkey assertion) only comes into existence once this call initiates the transfer, so the proof is always supplied on the follow-up authorize, never inline on this call. If an SMS code lapses, re-send it via POST /quotes/{quoteId}/authorize/resend.

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"
    ]
  }
}