Agent Operations

Create a transfer quote

Changed on Oct 28, 2026

Generate a quote for a cross-currency transfer on behalf of the authenticated agent's customer. Accounts referenced in the request must belong to the agent's customer. Requires the CREATE_QUOTES permission in the agent's policy. The destination is another embedded wallet or one of the customer's Spark addresses saved with POST /agents/me/external-accounts (ACCOUNT), an address on another chain (CHAIN_ADDRESS), or a BOLT11 Lightning invoice (LIGHTNING_INVOICE). Grid answers DESTINATION_NOT_ALLOWED for a Spark address that was refused, or is held for review, on any of the customer's records of it, under either prefix and including removed ones. A CHAIN_ADDRESS quote sends USDB. Grid pays the chain itself at a locked rate, so the amount the recipient receives is fixed when the quote is created and equals the quote's minimumReceivingAmount. A LIGHTNING_INVOICE quote debits the source wallet and pays exactly the invoice's amount, which it locks on the receiving side in satoshis, through the platform's Lightning invoice quote (POST /quotes). If the agent's defaultExecutionMode is APPROVAL_REQUIRED, or the quote amount exceeds the agent's approvalThresholds, the resulting transaction will require explicit approval before funds move.

post/agents/me/quotes

Request

Base URL
https://api.lightspark.com/grid/2025-10-13
URL
https://api.lightspark.com/grid/2025-10-13/agents/me/quotes
Auth
HTTP bearer

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

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.

Example request

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

Response

Transfer quote created successfully

idstring required

Unique identifier for this quote

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. The rate is fee-exclusive: Grid deducts feesIncluded from totalSendingAmount first, then converts the remainder at this rate to reach totalReceivingAmount.

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.

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.

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

Some destinations accept only certain purposes. A business payout to China must use one of the purposes listed in Supporting Documents, and each needs its own supporting documents.

documentIdsstring[]

IDs of the supporting documents attached to the payment behind this quote, as passed in documentIds on POST /quotes. Present only when the quote was created with documentIds. Grid returns such a quote only after it has attached every document. Call GET /payment-documents/{paymentDocumentId} for each document's details, such as its documentType and its ATTACHED status.

minimumReceivingAmountinteger nullable

Smallest amount the recipient receives, in the smallest unit of receivingCurrency, for a quote to a CHAIN_ADDRESS destination. Grid pays the chain itself at a locked rate, so this equals totalReceivingAmount. Null for a quote whose destination is not CHAIN_ADDRESS.

destinationSparkAddressstring

The Spark address this quote pays, when its destination is one of the customer's SPARK_WALLET external accounts.

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
  },
  "documentIds": [
    "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
    "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
    "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
  ],
  "scaChallenge": {
    "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
    "expiresAt": "2025-10-03T12:05:00Z",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  },
  "minimumReceivingAmount": 1000,
  "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
  "destinationChainAddress": {
    "destinationType": "CHAIN_ADDRESS",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "destinationLightningInvoice": {
    "destinationType": "LIGHTNING_INVOICE",
    "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
  }
}

Changes

Oct 28, 2026d996ddfb9d2b Revision changes
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
Oct 28, 20265abf2bb56bcb Revision changes
- warning
  added the new CORRIDOR_UNDER_MAINTENANCE enum value to the response property for the response status

Operation history (19 revisions)