Create a transfer quote

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/quotes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"source\": {\n    \"sourceType\": \"ACCOUNT\",\n    \"accountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n    \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\"\n  },\n  \"destination\": {\n    \"destinationType\": \"ACCOUNT\",\n    \"accountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\",\n    \"paymentRail\": \"ACH\"\n  },\n  \"lockedCurrencyAmount\": 1000\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/quotes")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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,
  "exchangeRate": 123,
  "feesIncluded": 10,
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
  "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"
      }
    }
  ],
  "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
  },
  "purposeOfPayment": "GIFT",
  "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",
    "factor": "SMS_OTP",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  },
  "minimumReceivingAmount": 1000,
  "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
  "destinationChainAddress": {
    "destinationType": "CHAIN_ADDRESS",
    "network": "BASE",
    "currency": "USDC",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "destinationLightningInvoice": {
    "destinationType": "LIGHTNING_INVOICE",
    "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNSUPPORTED_UMA_VERSION",
  "reason": "<string>",
  "details": {}
}

{
  "code": "PAYREQ_REQUEST_FAILED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "INVALID_PAYREQ_RESPONSE",
  "reason": "<string>",
  "details": {}
}

{
  "code": "SERVICE_UNAVAILABLE",
  "reason": "<string>",
  "details": {}
}

{
  "code": "LOOKUP_REQUEST_FAILED",
  "reason": "<string>",
  "details": {}
}

Agent Operations

Create a transfer quote

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 or the approvalThreshold of the spending pool the agent belongs to, the resulting transaction will require explicit approval before funds move.

POST

agents

quotes

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/quotes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"source\": {\n    \"sourceType\": \"ACCOUNT\",\n    \"accountId\": \"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965\",\n    \"customerId\": \"Customer:019542f5-b3e7-1d02-0000-000000000001\"\n  },\n  \"destination\": {\n    \"destinationType\": \"ACCOUNT\",\n    \"accountId\": \"ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123\",\n    \"paymentRail\": \"ACH\"\n  },\n  \"lockedCurrencyAmount\": 1000\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/quotes")
  .post(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "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,
  "exchangeRate": 123,
  "feesIncluded": 10,
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
  "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"
      }
    }
  ],
  "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
  },
  "purposeOfPayment": "GIFT",
  "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",
    "factor": "SMS_OTP",
    "availableFactors": [
      "SMS_OTP"
    ],
    "purpose": "PAYOUT",
    "passkeyAssertionOptions": {},
    "passkeyAllowedOrigins": [
      "https://app.example.com"
    ]
  },
  "minimumReceivingAmount": 1000,
  "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
  "destinationChainAddress": {
    "destinationType": "CHAIN_ADDRESS",
    "network": "BASE",
    "currency": "USDC",
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "destinationLightningInvoice": {
    "destinationType": "LIGHTNING_INVOICE",
    "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
  }
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "UNSUPPORTED_UMA_VERSION",
  "reason": "<string>",
  "details": {}
}

{
  "code": "PAYREQ_REQUEST_FAILED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

{
  "code": "INVALID_PAYREQ_RESPONSE",
  "reason": "<string>",
  "details": {}
}

{
  "code": "SERVICE_UNAVAILABLE",
  "reason": "<string>",
  "details": {}
}

{
  "code": "LOOKUP_REQUEST_FAILED",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Headers

Idempotency-Key

string

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.

Maximum string length: 255

Example:

"<uuid>"

Body

application/json

A transfer quote requested by an agent. The source is an EMBEDDED_WALLET internal account of the agent's customer. The destination is either an ACCOUNT: another EMBEDDED_WALLET on the platform, or one of the customer's active SPARK_WALLET external accounts in the source's currency; an address on another chain (CHAIN_ADDRESS); or a BOLT11 Lightning invoice (LIGHTNING_INVOICE).

A CHAIN_ADDRESS quote sends USDB. With lockedCurrencySide SENDING it commits to the USDB amount; with RECEIVING it commits to exactly the amount the destination receives, in the smallest unit of the destination's currency, and the fees are added to the USDB sent. Grid pays the chain itself at a locked rate, so the amount the destination receives is fixed when the quote is created and returned as minimumReceivingAmount. When Grid cannot deliver a RECEIVING amount exactly, it refuses the quote with 400 EXACT_AMOUNT_UNAVAILABLE.

A LIGHTNING_INVOICE quote debits the source wallet and pays exactly the invoice's amount. Its lockedCurrencySide must be RECEIVING and its lockedCurrencyAmount the invoice's amount in satoshis; the fees are added to the amount debited. It is the platform's own Lightning invoice quote (see POST /quotes), so the same invoice rules and the one-live-quote rule apply: another quote for an invoice is refused with 409 INVOICE_ALREADY_USED while an earlier one can still be executed, except a repeat of the same request with the same Idempotency-Key.

source

Account · object

required

Source account details

Account
Real-time Funding

Show child attributes

destination

Account · object

required

Destination of an agent quote.

Account
Chain Address
Lightning Invoice

Show child attributes

lockedCurrencySide

enum<string>

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

Available options:

SENDING,

RECEIVING

lockedCurrencyAmount

integer<int64>

required

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

Required range: x <= 9000000000000000

Example:

1000

Response

Transfer quote created successfully

A quote created by an agent. For a CHAIN_ADDRESS destination, the quote's destination names the external account Grid recorded for the address, and destinationChainAddress names the address itself. For a LIGHTNING_INVOICE destination, destination names the external account Grid recorded for the invoice, and destinationLightningInvoice names the invoice itself.

string

required

Unique identifier for this quote

Example:

"Quote:019542f5-b3e7-1d02-0000-000000000006"

status

enum<string>

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.

Available options:

PENDING,

PENDING_AUTHORIZATION,

PROCESSING,

COMPLETED,

FAILED,

EXPIRED

Example:

"PENDING"

createdAt

string<date-time>

required

When this quote was created

Example:

"2025-10-03T12:00:00Z"

expiresAt

string<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.

Example:

"2025-10-03T12:05:00Z"

source

Account · object

required

Source account details

Account
Real-time Funding

Show child attributes

destination

Account · object

required

Destination account details

Account
UMA Address

Show child attributes

sendingCurrency

object

required

Currency for the sending amount

Show child attributes

receivingCurrency

object

required

Currency for the receiving amount

Show child attributes

totalSendingAmount

integer<int64>

required

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

Example:

123010

totalReceivingAmount

integer<int64>

required

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

Example:

1000

exchangeRate

number

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.

feesIncluded

integer<int64>

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.

Required range: x >= 0

Example:

10

transactionId

string

required

The ID of the transaction created from this quote.

Example:

"Transaction:019542f5-b3e7-1d02-0000-000000000005"

platformFeesIncluded

integer<int64>

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.

Required range: x >= 0

Example:

5

paymentInstructions

object[]

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

Show child attributes

Example:

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

counterpartyInformation

object

Additional information about the counterparty, if available and required by the platform in their configuration.

Example:

{
  "FULL_NAME": "John Sender",
  "BIRTH_DATE": "1985-06-15",
  "NATIONALITY": "DE"
}

rateDetails

object

Details about the rate and fees for the transaction.

Show child attributes

purposeOfPayment

enum<string>

The purpose of payment the quote was created with. Present only when the quote request set purposeOfPayment.

Available options:

GIFT,

SELF,

GOODS_OR_SERVICES,

EDUCATION,

HEALTH_OR_MEDICAL,

REAL_ESTATE_PURCHASE,

TAX_PAYMENT,

LOAN_PAYMENT,

UTILITY_BILL,

DONATION,

TRAVEL,

FAMILY_SUPPORT,

SALARY_PAYMENT,

EXPORTED_GOODS_PREPAYMENT,

EXPORTED_GOODS_POSTPAYMENT,

SERVICE_CHARGES,

OFFICE_EXPENSES,

DELIVERY_FEES,

HOTEL_ACCOMMODATION,

COMMISSION_ON_GOODS,

COMMISSION_ON_SERVICES,

ACCOUNTING_SERVICES,

EXHIBITION_SERVICES,

OTHER

documentIds

string[]

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.

Example:

[
  "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
  "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
  "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
]

scaChallenge

object

Present only while status is PENDING_AUTHORIZATION: the Strong Customer Authentication challenge to satisfy before this quote can be executed (or, for realtime-funding sources, before paymentInstructions are issued). Omitted for customers outside SCA-regulated regions (non-EU).

Show child attributes

minimumReceivingAmount

integer<int64> | null

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.

Example:

1000

destinationSparkAddress

string

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

Example:

"spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"

destinationChainAddress

Chain Address · object

The chain, address and stablecoin this quote pays, when it was created with a CHAIN_ADDRESS destination.

Show child attributes

destinationLightningInvoice

Lightning Invoice · object

The invoice this quote pays, when it was created with a LIGHTNING_INVOICE destination.

Show child attributes

Using the API

API documentation

Create a transfer quote

Authorizations

Headers

Body

Response