openapi: 3.2.0 info: title: Grid Agent Management API description: API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. version: '2025-10-13' contact: name: Lightspark Support email: support@lightspark.com license: name: Proprietary url: https://lightspark.com/terms servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server security: - BasicAuth: [] - AgentAuth: [] tags: - name: Agent Management description: 'Endpoints for creating and managing agents (experimental), called by the partner''s backend using platform credentials. Covers the full agent lifecycle: creation, policy configuration, pausing, deletion, the device code installation flow, and approving or rejecting transactions initiated by agents.' paths: /agents: post: summary: Create an agent description: Create a new agent with a specified policy. Returns the created agent and a device code that must be redeemed by the agent software to complete installation. operationId: createAgent tags: - Agent Management security: - BasicAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentCreateRequest' responses: '201': description: Agent created successfully content: application/json: schema: $ref: '#/components/schemas/AgentCreateResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Customer not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' get: summary: List agents description: Retrieve a paginated list of agents for the authenticated platform. operationId: listAgents tags: - Agent Management security: - BasicAuth: [] parameters: - name: customerId in: query description: Filter by customer ID required: false schema: type: string - name: isPaused in: query description: Filter by paused status required: false schema: type: boolean - name: isConnected in: query description: Filter by connection status (whether the device code has been redeemed) required: false schema: type: boolean - name: createdAfter in: query description: Filter agents created after this timestamp (inclusive) required: false schema: type: string format: date-time - name: createdBefore in: query description: Filter agents created before this timestamp (inclusive) required: false schema: type: string format: date-time - name: updatedAfter in: query description: Filter agents updated after this timestamp (inclusive) required: false schema: type: string format: date-time - name: updatedBefore in: query description: Filter agents updated before this timestamp (inclusive) required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return (default 20, max 100) required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query description: Cursor for pagination (returned from previous request) required: false schema: type: string responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/AgentListResponse' '400': description: Bad request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Customer not found when filtering by customerId content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/approvals: get: summary: List agent transaction approval requests description: Retrieve a paginated list of agent actions that require platform approval. Filter by `agentId` or `customerId` to scope results to a specific agent or customer. Approve or reject individual actions via `POST /agents/{agentId}/actions/{actionId}/approve` or `POST /agents/{agentId}/actions/{actionId}/reject`. operationId: listAgentApprovals tags: - Agent Management security: - BasicAuth: [] parameters: - name: agentId in: query description: Filter by agent ID required: false schema: type: string - name: customerId in: query description: Filter by customer ID required: false schema: type: string - name: startDate in: query description: Filter by start date (inclusive) in ISO 8601 format required: false schema: type: string format: date-time - name: endDate in: query description: Filter by end date (inclusive) in ISO 8601 format required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return (default 20, max 100) required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query description: Cursor for pagination (returned from previous request) required: false schema: type: string - name: sortOrder in: query description: Order to sort results in required: false schema: type: string enum: - asc - desc default: desc responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/AgentActionListResponse' '400': description: Bad request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/{agentId}: parameters: - name: agentId in: path description: System-generated unique agent identifier required: true schema: type: string get: summary: Get agent by ID description: Retrieve an agent by its system-generated ID. operationId: getAgentById tags: - Agent Management security: - BasicAuth: [] responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/Agent' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' patch: summary: Update agent description: Update an agent's name or paused state. operationId: updateAgent tags: - Agent Management security: - BasicAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentUpdateRequest' responses: '200': description: Agent updated successfully content: application/json: schema: $ref: '#/components/schemas/Agent' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' delete: summary: Delete agent description: Permanently delete an agent. Connected agent software will lose access immediately. operationId: deleteAgent tags: - Agent Management security: - BasicAuth: [] responses: '204': description: Agent deleted successfully '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/{agentId}/policy: parameters: - name: agentId in: path description: System-generated unique agent identifier required: true schema: type: string patch: summary: Update agent policy description: Partially update an agent's policy. Only provided fields will be updated; omitted fields retain their current values. Policy changes take effect immediately. The spending limits currency is immutable; attempting to change it returns a 400 response. operationId: updateAgentPolicy tags: - Agent Management security: - BasicAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentPolicyUpdateRequest' responses: '200': description: Agent policy updated successfully content: application/json: schema: $ref: '#/components/schemas/Agent' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/{agentId}/device-codes: parameters: - name: agentId in: path description: System-generated unique agent identifier required: true schema: type: string post: summary: Regenerate a device code description: Generate a new device code for an existing agent. Use this when the original device code has expired before being redeemed, or when the agent software needs to be reinstalled. An agent has at most one unredeemed device code, so regenerating invalidates the one issued before it. operationId: regenerateAgentDeviceCode tags: - Agent Management security: - BasicAuth: [] responses: '201': description: New device code generated successfully content: application/json: schema: $ref: '#/components/schemas/AgentDeviceCode' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent not found content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: Conflict - Agent already has an active connection and cannot regenerate a device code content: application/json: schema: $ref: '#/components/schemas/Error409' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/{agentId}/actions/{actionId}/approve: parameters: - name: agentId in: path description: System-generated unique agent identifier required: true schema: type: string - name: actionId in: path description: Unique identifier of the agent action to approve required: true schema: type: string post: summary: Approve an agent action description: 'Approve a pending agent action, allowing Grid to proceed with execution. The action must have status `PENDING_APPROVAL`. Once approved, Grid executes the underlying operation (quote execution or transfer) and the action transitions to `APPROVED`. For `EXECUTE_QUOTE` actions, note that the underlying quote may have expired between submission and approval — in that case the action will transition to `FAILED` instead. This endpoint is called by the platform''s backend using platform credentials, not by the agent itself.' operationId: approveAgentAction tags: - Agent Management security: - BasicAuth: [] responses: '200': description: Action approved successfully. Returns the updated AgentAction. content: application/json: schema: $ref: '#/components/schemas/AgentAction' '400': description: Bad request - Action cannot be approved content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent or action not found content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: Conflict - Action is not pending approval or has already been processed content: application/json: schema: $ref: '#/components/schemas/Error409' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/{agentId}/actions/{actionId}/reject: parameters: - name: agentId in: path description: System-generated unique agent identifier required: true schema: type: string - name: actionId in: path description: Unique identifier of the agent action to reject required: true schema: type: string post: summary: Reject an agent action description: 'Reject a pending agent action, preventing execution. The action must have status `PENDING_APPROVAL`. Once rejected, the action transitions to `REJECTED` and the underlying operation is not executed. This endpoint is called by the platform''s backend using platform credentials, not by the agent itself.' operationId: rejectAgentAction tags: - Agent Management security: - BasicAuth: [] requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/AgentActionRejectRequest' responses: '200': description: Action rejected successfully. Returns the updated AgentAction. content: application/json: schema: $ref: '#/components/schemas/AgentAction' '400': description: Bad request - Action cannot be rejected content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Agent or action not found content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: Conflict - Action is not pending approval or has already been processed content: application/json: schema: $ref: '#/components/schemas/Error409' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/device-codes/status: post: summary: Get device code status description: Check the status of a device code. Use this to poll for agent installation completion after creating an agent. operationId: getAgentDeviceCodeStatus tags: - Agent Management security: - BasicAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentDeviceCodeRequest' responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/AgentDeviceCodeStatusResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Device code not found content: application/json: schema: $ref: '#/components/schemas/Error404' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' /agents/device-codes/redeem: post: summary: Redeem device code description: 'Redeem a device code to obtain agent credentials. This endpoint is called by the agent software during installation. On success, returns a Bearer access token that the agent uses for all subsequent API calls. The token is returned only once and must be stored securely. This endpoint does not require platform authentication — the device code itself serves as proof of authorization. A code can be redeemed only once and only before its `expiresAt`. Redemption is rate limited in fixed 60-second windows. Calls without platform credentials are limited to 10 per client IP address and 1,000 across all such callers; calls made with platform credentials are limited to 600 per platform instead. A caller over a limit receives `429` with `RATE_LIMITED` and should back off until the window resets before retrying. If the limit cannot be checked, the call is also rejected with `429`.' operationId: redeemAgentDeviceCode tags: - Agent Management security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentDeviceCodeRequest' responses: '200': description: Device code redeemed successfully content: application/json: schema: $ref: '#/components/schemas/AgentDeviceCodeRedeemResponse' '400': description: Bad request (e.g., code already redeemed or expired) content: application/json: schema: $ref: '#/components/schemas/Error400' '403': description: Forbidden - Agents API is not enabled for the platform content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Device code not found content: application/json: schema: $ref: '#/components/schemas/Error404' '429': description: Too many requests. Returned with `RATE_LIMITED`. content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' components: schemas: WireRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: 'Status of the wire on Fedwire. | Status | Description | |--------|-------------| | `PENDING` | Submitted to Fedwire and not yet delivered. | | `SETTLED` | Fedwire delivered the wire. | | `FAILED` | Fedwire or the receiving bank rejected the wire and no funds moved. |' example: SETTLED PaymentSwiftAccountInfo: title: SWIFT Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SwiftAccountInfo' - type: object required: - accountHolderName properties: accountHolderName: type: string description: The name of the account holder as it must appear on the wire. Remitting banks match this against the beneficiary name field, so payers should copy it exactly. example: Acme Exports Pte Ltd minLength: 1 maxLength: 255 bankAddress: type: string description: The address of the bank holding the account, when known. example: 12 Marina Boulevard, Singapore 018982 minLength: 1 maxLength: 1024 reference: type: string description: Reference code to include with the payment when present. SWIFT payments are attributed by the destination account number/IBAN, so this account type typically requires no reference. example: UMA-Q12345-REF SwiftAccountInfoBase: type: object description: 'At least one of accountNumber or iban is always present: IBAN-only corridors (e.g. BR, GB) use iban, other corridors use accountNumber, and both appear when the bank exposes both identifiers for the same account.' required: - accountType - swiftCode - bankName - country properties: accountType: type: string enum: - SWIFT_ACCOUNT country: type: string description: The ISO 3166-1 alpha-2 country code of the bank account example: NG minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ swiftCode: type: string description: The SWIFT/BIC code of the bank example: DEUTDEFF minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ bankName: type: string description: The name of the bank example: Deutsche Bank minLength: 1 maxLength: 255 accountNumber: type: string description: The bank account number. Required for most corridors. Use iban instead for IBAN-only corridors (e.g. BR, GB). example: '1234567890' minLength: 1 maxLength: 34 iban: type: string description: The IBAN of the bank account. Required for IBAN-only corridors (e.g. BR, GB). Use accountNumber for all other corridors. example: GB29NWBK60161331926819 minLength: 15 maxLength: 34 pattern: ^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{11,30}$ example: accountType: SWIFT_ACCOUNT country: NG swiftCode: DEUTDEFF bankName: Deutsche Bank accountNumber: '1234567890' PurposeOfPayment: type: string description: '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](https://docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment#supporting-documents), and each needs its own supporting documents.' enum: - 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 AgentActionFailureReason: type: string enum: - QUOTE_EXPIRED - POLICY_DENIED - AGENT_INACTIVE - EXECUTION_FAILED - PRICE_MOVED - ADDRESS_REFUSED description: 'Why an agent action has status `FAILED`. | Reason | Description | |--------|-------------| | `QUOTE_EXPIRED` | The action''s quote expired before execution | | `POLICY_DENIED` | The agent policy no longer allowed the action | | `AGENT_INACTIVE` | The agent was paused or deleted before execution | | `EXECUTION_FAILED` | Grid could not execute the approved action | | `PRICE_MOVED` | A quote to a `CHAIN_ADDRESS` would no longer deliver its `minimumReceivingAmount` when it executed, so Grid did not send | | `ADDRESS_REFUSED` | Grid refused the send''s destination before it signed the send: the destination is no longer one the agent may send to (for example, a Spark address removed from the customer''s saved addresses), or one of the customer''s records of the address was refused or is held for review. A `CHAIN_ADDRESS` that screening refuses fails with `EXECUTION_FAILED` | ' BaseDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/DestinationType' AgentSendCurrency: type: string enum: - USDC - USDT description: Asset an agent can send to an address on another chain. `TRON` supports `USDT` only, and `BASE` supports `USDC` only. UsdBankAccountDetails: title: US Bank Account Details type: object description: 'The account on the other end of the transfer: the sender''s account on a source, the recipient''s account on a destination.' properties: accountHolderName: type: string description: Name of the account holder. example: John Sender routingNumber: type: string description: 9-digit ABA routing number of the account's bank. example: '021000021' accountNumber: type: string description: Account number, masked to its last four digits. example: '****6789' AccountQuoteSource: title: Account allOf: - $ref: '#/components/schemas/BaseQuoteSource' - type: object required: - accountId - sourceType properties: sourceType: type: string enum: - ACCOUNT accountId: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 customerId: type: string description: The customer on whose behalf the transaction is being initiated. Required when funding from a `BULK_SETTLEMENT` account. The customer is never the account owner, because the platform owns the account. When funding from an FBO account, this field is optional. If you omit it, the transaction is initiated on behalf of the platform. For any other account, it defaults to the account owner's customerId. example: Customer:019542f5-b3e7-1d02-0000-000000000001 description: Source account details Error429: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | RATE_LIMITED | Too many requests in a short window; retry after the interval indicated by the `Retry-After` response header | | DAILY_VOLUME_LIMIT_EXCEEDED | The requested amount would exceed the configured daily volume limit for this trade corridor or withdrawal currency | ' enum: - RATE_LIMITED - DAILY_VOLUME_LIMIT_EXCEEDED reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true AgentDeviceCodeRequest: type: object required: - code properties: code: type: string description: The device code. example: jqzJR3AgI9OAwb_enypARw StablecoinAssetType: type: string description: Type of asset enum: - USDC - USDT AgentApprovalThresholds: type: object description: Thresholds that force approval for high-value transactions, overriding the default execution mode. The threshold currency must equal the policy's spending limits currency. When a transaction is denominated in a different currency, Grid converts it to the policy currency at evaluation time. properties: currency: type: string description: ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set and must equal `spendingLimits.currency`. example: USD amount: type: - integer - 'null' description: If set, any transaction above this amount (in the smallest unit of the specified currency) will require explicit approval even when the agent's defaultExecutionMode is AUTO. Null means no threshold override. example: 100000 AgentListResponse: type: object required: - data - hasMore properties: data: type: array description: List of agents matching the filter criteria. items: $ref: '#/components/schemas/Agent' hasMore: type: boolean description: Indicates if more results are available beyond this page. nextCursor: type: string description: Cursor to retrieve the next page of results (only present if hasMore is true). totalCount: type: integer description: Total number of agents matching the criteria (excluding pagination). AgentAction: type: object description: An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type. required: - id - agentId - customerId - platformCustomerId - status - type - expiresAt - createdAt - updatedAt properties: id: type: string description: System-generated unique identifier for this action. example: AgentAction:019542f5-b3e7-1d02-0000-000000000099 agentId: type: string description: The agent that submitted this action. example: Agent:019542f5-b3e7-1d02-0000-000000000042 customerId: type: string description: The customer on whose behalf the action was submitted. example: Customer:019542f5-b3e7-1d02-0000-000000000010 platformCustomerId: type: string description: Platform-specific ID of the customer. example: user-a1b2c3 status: $ref: '#/components/schemas/AgentActionStatus' type: $ref: '#/components/schemas/AgentActionType' quote: allOf: - $ref: '#/components/schemas/AgentQuote' description: The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. Present for `EXECUTE_QUOTE`. transaction: allOf: - $ref: '#/components/schemas/TransactionOneOf' description: The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is `PENDING_APPROVAL` or `REJECTED`. rejectionReason: type: string description: Human-readable reason provided by the platform when rejecting the action. Only present when status is `REJECTED`. example: Transaction amount exceeds customer's current risk limit. failureReason: $ref: '#/components/schemas/AgentActionFailureReason' description: Machine-readable reason the action failed. Only present when status is `FAILED`; `rejectionReason` is used only for `REJECTED` actions. expiresAt: type: string format: date-time description: When the action expires. For `EXECUTE_QUOTE`, this is the quote's own expiry. A `PENDING_APPROVAL` action that reaches this time transitions to `FAILED` with `failureReason` `QUOTE_EXPIRED`; approval never creates a replacement quote. example: '2025-10-03T15:05:00Z' createdAt: type: string format: date-time description: When the action was submitted by the agent. example: '2025-10-03T15:00:00Z' updatedAt: type: string format: date-time description: When the action was last updated. example: '2025-10-03T15:02:00Z' AgentActionType: type: string enum: - EXECUTE_QUOTE description: 'The type of action the agent is requesting. | Type | Description | |------|-------------| | `EXECUTE_QUOTE` | Execute a quote | ' PaymentBrlAccountInfo: title: BRL Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - qrCode properties: accountType: type: string enum: - BRL_ACCOUNT qrCode: type: string description: A PIX QR code payload that can be used to fund the transaction. This can be rendered as a QR code image or pasted into a PIX-compatible banking app. minLength: 1 OutgoingTransactionFailureReason: type: string enum: - QUOTE_EXPIRED - QUOTE_RATE_UNAVAILABLE - QUOTE_EXECUTION_FAILED - FUNDING_AMOUNT_MISMATCH - SCA_NOT_COMPLETED - PAYOUT_RETURNED - LIMIT_EXCEEDED - ACCOUNT_CANNOT_RECEIVE - ACCOUNT_INVALID - COMPLIANCE_REJECTED - LIGHTNING_PAYMENT_FAILED - COUNTERPARTY_POST_TX_FAILED - SWEEP_AMOUNT_OUT_OF_RANGE - SWEEP_QUOTE_FAILED description: 'Reason for failure of an outgoing transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. When a payout partner rejects or fails a payment, one of the granular payout reasons (`PAYOUT_RETURNED`, `LIMIT_EXCEEDED`, `ACCOUNT_CANNOT_RECEIVE`, `ACCOUNT_INVALID`, `COMPLIANCE_REJECTED`) is returned when available. `COUNTERPARTY_POST_TX_FAILED` is a coarse fallback used only when no granular reason is available. `SCA_NOT_COMPLETED` means the customer did not satisfy the Strong Customer Authentication challenge before it expired, so the transaction was never authorized and no funds were moved. Only occurs for customers in a region where SCA is required (e.g. the EU). Create a new quote to try again, and have the customer authorize it while the challenge is live. | Reason | Description | |--------|-------------| | `QUOTE_EXPIRED` | The quote was not executed before its expiry window | | `QUOTE_RATE_UNAVAILABLE` | The quoted exchange rate was no longer available when the quote was executed, so nothing was exchanged. Create a new quote to get a current rate | | `QUOTE_EXECUTION_FAILED` | The quote could not be executed. Covers any internal failure on the way to settlement, whether or not funds were debited — a debited amount is refunded automatically | | `FUNDING_AMOUNT_MISMATCH` | The funds received did not match the expected amount | | `SCA_NOT_COMPLETED` | The customer did not complete the Strong Customer Authentication challenge before it expired | | `PAYOUT_RETURNED` | The receiving bank accepted the payout and then returned or reversed it | | `LIMIT_EXCEEDED` | The payout exceeds a recipient-, account-, or corridor-level limit at the partner | | `ACCOUNT_CANNOT_RECEIVE` | The account exists but can''t accept this payment — dormant, frozen, restricted, or the currency or payment rail isn''t supported for that account. A sweep whose rule names a rail the destination cannot accept reports this | | `ACCOUNT_INVALID` | The recipient account couldn''t be found or the details are wrong — bad IBAN/account number, beneficiary not found, or account closed | | `COMPLIANCE_REJECTED` | The payout partner rejected the recipient on compliance grounds — sanctions, watchlist, or KYC/AML screening | | `LIGHTNING_PAYMENT_FAILED` | Deprecated — superseded by `QUOTE_EXECUTION_FAILED`. The Lightning settlement leg failed | | `COUNTERPARTY_POST_TX_FAILED` | Deprecated — coarse fallback retained for historical transactions when no granular payout reason is available | | `SWEEP_AMOUNT_OUT_OF_RANGE` | The amount was outside the range the corridor to the rule''s destination can carry — below its minimum or above its maximum. The rule''s `minimumAmount` and `maximumAmount` give the current band | | `SWEEP_QUOTE_FAILED` | Grid could not price the sweep to the rule''s destination. A sweep that was priced and then failed on the way to settlement reports `QUOTE_EXECUTION_FAILED`, the same as any other payout | The `SWEEP_*` reasons apply to a payment that settled into a rule-based account and could not be swept onward. A rule-based account never holds a balance, so the funds are moved to the account holder''s own account in the same currency. ' TransactionDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionDestination' - $ref: '#/components/schemas/UmaAddressTransactionDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountTransactionDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionDestination' Agent: type: object description: A programmatic agent with scoped permissions and a spending policy, used to automate payment workflows. required: - id - name - customerId - isPaused - isConnected - policy - usage - createdAt - updatedAt properties: id: type: string description: System-generated unique identifier for the agent. example: Agent:019542f5-b3e7-1d02-0000-000000000001 name: type: string description: Human-readable name for the agent. example: Payroll Automation Agent customerId: type: string description: The ID of the customer this agent operates on behalf of. example: Customer:019542f5-b3e7-1d02-0000-000000000001 isPaused: type: boolean description: Whether the agent is currently paused. Paused agents cannot initiate any actions. example: false isConnected: type: boolean description: Whether the agent has been installed and connected (i.e., its device code has been redeemed). example: true policy: $ref: '#/components/schemas/AgentPolicy' usage: $ref: '#/components/schemas/AgentUsage' createdAt: type: string format: date-time description: Creation timestamp. example: '2025-07-21T17:32:28Z' updatedAt: type: string format: date-time description: Last update timestamp. example: '2025-07-21T17:32:28Z' AgentExecutionMode: type: string enum: - AUTO - APPROVAL_REQUIRED description: 'Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution.' AchPaymentRail: type: string enum: - ACH - ACH_SAME_DAY TransactionDirection: type: string enum: - CREDIT - DEBIT description: 'Whether the transaction credits (funds in) or debits (funds out) the customer''s account. Independent of `type`: an incoming transaction is normally a `CREDIT`, but an inbound ACH pull, for example, is an `INCOMING` transaction with a `DEBIT` direction.' TransactionSourceOneOf: oneOf: - $ref: '#/components/schemas/AccountTransactionSource' - $ref: '#/components/schemas/UmaAddressTransactionSource' - $ref: '#/components/schemas/RealtimeFundingTransactionSource' discriminator: propertyName: sourceType mapping: ACCOUNT: '#/components/schemas/AccountTransactionSource' UMA_ADDRESS: '#/components/schemas/UmaAddressTransactionSource' REALTIME_FUNDING: '#/components/schemas/RealtimeFundingTransactionSource' MxnAccountInfoBase: type: object required: - accountType - clabeNumber properties: accountType: type: string enum: - MXN_ACCOUNT clabeNumber: type: string description: The CLABE number of the bank example: '123456789012345678' minLength: 18 maxLength: 18 pattern: ^[0-9]{18}$ example: accountType: MXN_ACCOUNT clabeNumber: '123456789012345678' Error401: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | ' enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true RefundReason: type: string enum: - TRANSACTION_FAILED - USER_CANCELLATION - TIMEOUT description: Reason for the refund example: TRANSACTION_FAILED Error403: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | FORBIDDEN | Insufficient permissions | | USER_NOT_READY | Customer exists but is not ready for operation | | COUNTERPARTY_NOT_ALLOWED | Counterparty has not been enabled for your account | | VELOCITY_LIMIT_EXCEEDED | Counterparty has exceeded velocity limits | | END_USER_TERMS_NOT_ACCEPTED | Customer has not accepted the End User Terms | | CUSTOMER_NOT_VERIFIED | The customer is not verified and cannot perform this action | | SANCTION_BLOCKED | Blocked by sanction screening | | DESTINATION_NOT_ALLOWED | The agent may not pay this destination | ' enum: - FORBIDDEN - USER_NOT_READY - COUNTERPARTY_NOT_ALLOWED - VELOCITY_LIMIT_EXCEEDED - END_USER_TERMS_NOT_ACCEPTED - CUSTOMER_NOT_VERIFIED - SANCTION_BLOCKED - DESTINATION_NOT_ALLOWED reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true AccountTransactionDestination: title: Account Destination allOf: - $ref: '#/components/schemas/BaseTransactionDestination' - type: object required: - accountId - destinationType properties: destinationType: type: string enum: - ACCOUNT accountId: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Destination account details AgentPermission: type: string enum: - VIEW_TRANSACTIONS - CREATE_QUOTES - EXECUTE_QUOTES - MANAGE_EXTERNAL_ACCOUNTS - RECEIVE_FUNDS - MANAGE_IDENTITY - MANAGE_CARDS description: 'Permission granted to an agent that determines what actions it can perform. VIEW_TRANSACTIONS: Can list and retrieve transactions and account balances. CREATE_QUOTES: Can create quotes. EXECUTE_QUOTES: Can execute quotes. MANAGE_EXTERNAL_ACCOUNTS: Can create and manage external accounts. RECEIVE_FUNDS: Can create deposit targets for receiving funds. MANAGE_IDENTITY: Can read and update customer identity information and start verification. MANAGE_CARDS: Can read, tighten, and freeze its cards.' PaymentMxnAccountInfo: title: MXN Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/MxnAccountInfo' - type: object required: - reference properties: reference: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF UmaAddressDestination: title: UMA Address allOf: - $ref: '#/components/schemas/BaseDestination' - type: object required: - umaAddress - destinationType - currency properties: destinationType: type: string enum: - UMA_ADDRESS umaAddress: type: string maxLength: 200 description: UMA address of the recipient example: $receiver@uma.domain.com currency: type: string description: Currency code for the destination. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. example: EUR description: UMA address destination details PaymentArsAccountInfo: title: ARS Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - accountNumber properties: accountType: type: string enum: - ARS_ACCOUNT accountNumber: type: string description: The static CVU (Clave Virtual Uniforme) bank account number to pay to. minLength: 22 maxLength: 22 pattern: ^\d{22}$ example: '0000003100074052501434' UsdAccountInfoBase: type: object required: - accountType - accountNumber - routingNumber properties: accountType: type: string enum: - USD_ACCOUNT accountNumber: type: string description: The account number of the bank minLength: 1 maxLength: 34 routingNumber: type: string description: The ABA routing number example: '021000021' minLength: 9 maxLength: 9 pattern: ^[0-9]{9}$ bankName: type: string description: The name of the financial institution holding the account. Optional on every rail, and recommended for wires, where it identifies the beneficiary's institution on the payment message. Not checked against `GET /discoveries`. minLength: 1 maxLength: 140 example: Chase Bank intermediaryBankName: type: string description: The name of the intermediary financial institution, for accounts reachable only through a correspondent bank. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. example: JPMorgan Chase Bank minLength: 1 maxLength: 140 intermediaryRoutingNumber: type: string description: The ABA routing number of the intermediary financial institution. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. example: '021000021' minLength: 9 maxLength: 9 pattern: ^[0-9]{9}$ fiToFiInformation: type: string description: Bank-to-bank instructions carried alongside the payment. Used on the WIRE rail; ignored on ACH, RTP and FEDNOW. example: /BNF/Invoice 4471 maxLength: 210 example: accountType: USD_ACCOUNT accountNumber: '1234567890' routingNumber: '021000021' bankName: Chase Bank intermediaryBankName: JPMorgan Chase Bank intermediaryRoutingNumber: '021000021' fiToFiInformation: /BNF/Invoice 4471 bankAccountType: CHECKING UsdAccountInfo: allOf: - $ref: '#/components/schemas/UsdAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - ACH - ACH_SAME_DAY - WIRE - RTP - FEDNOW bankAccountType: type: string description: Whether the account is a checking or a savings account. Grid uses this to set the ACH transaction code, so a value that does not match the account causes the receiving bank to return a notification of change. enum: - CHECKING - SAVINGS example: CHECKING QuoteDestinationOneOf: oneOf: - $ref: '#/components/schemas/AccountDestination' - $ref: '#/components/schemas/UmaAddressDestination' discriminator: propertyName: destinationType mapping: ACCOUNT: '#/components/schemas/AccountDestination' UMA_ADDRESS: '#/components/schemas/UmaAddressDestination' UmaAddressTransactionDestination: title: UMA Address Destination allOf: - $ref: '#/components/schemas/BaseTransactionDestination' - type: object required: - umaAddress - destinationType properties: destinationType: type: string enum: - UMA_ADDRESS umaAddress: type: string description: UMA address of the recipient example: $receiver@uma.domain.com description: UMA address destination details BaseWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - BASE_WALLET address: type: string description: Base eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' SparkWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SPARK_WALLET address: type: string description: Spark wallet address example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu PaymentEthereumWalletInfo: title: Ethereum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EthereumWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' PlasmaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - PLASMA_WALLET address: type: string description: Plasma wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' AgentDeviceCodeStatus: type: string description: 'The current status of the device code. - `PENDING`: The code is active and has not been redeemed. - `REDEEMED`: The code was successfully redeemed. - `EXPIRED`: The code expired before it was redeemed. - `INVALIDATED`: The code was superseded or otherwise invalidated before it was redeemed. ' enum: - PENDING - REDEEMED - EXPIRED - INVALIDATED example: PENDING CardTransactionStatus: type: string enum: - AUTHORIZED - PARTIALLY_SETTLED - SETTLED - DECLINED - VOIDED - EXCEPTION description: 'Lifecycle status of a card transaction. The status tracks the authorization outcome and settlement — a return against a purchase is its own dated `CREDIT` row linked to the purchase via `originalTransactionId`, not a status of its own. | Status | Description | |--------|-------------| | `AUTHORIZED` | The auth has been approved and a hold placed on the funding source; no clearing has arrived yet. | | `PARTIALLY_SETTLED` | At least one clearing has arrived and posted, but more clearings are still expected (split shipments, tips, multi-leg trips). | | `SETTLED` | All clearings for the auth have posted and the transaction is closed against the funding source. A `RETURN` received afterwards keeps the purchase `SETTLED`; the return appears as its own `CREDIT` transaction. | | `DECLINED` | The authorization was declined before any money moved. Declines carry no settlement and must be excluded from cardholder statements. | | `VOIDED` | The authorization was fully reversed or expired before any clearing posted, so the hold closed without moving money. `authorizedAmount` reports what is still held, normally 0, and `settledAmount` is absent. | | `EXCEPTION` | The transaction settled to the card network but the corresponding pull from the funding source failed (e.g. balance no longer covers the post-hoc clearing). Surfaces high-urgency alerts and is the dashboard query for stuck reconciliations. | ' EurAccountInfoBase: type: object required: - accountType - iban properties: accountType: type: string enum: - EUR_ACCOUNT iban: type: string description: The IBAN of the bank account example: DE89370400440532013000 minLength: 15 maxLength: 34 pattern: ^[A-Z]{2}[0-9]{2}[A-Za-z0-9]{11,30}$ swiftCode: type: string description: The SWIFT/BIC code of the bank. When omitted, Grid derives it from the IBAN when possible. Provide it when automatic derivation is unavailable. example: DEUTDEFF minLength: 8 maxLength: 11 pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$ example: accountType: EUR_ACCOUNT iban: DE89370400440532013000 swiftCode: DEUTDEFF RealtimeFundingQuoteSource: title: Real-time Funding allOf: - $ref: '#/components/schemas/BaseQuoteSource' - type: object required: - currency - sourceType properties: sourceType: type: string enum: - REALTIME_FUNDING customerId: type: string description: Source customer ID. If this transaction is being initiated on behalf of a customer, this is required. If customerId is not provided, the quote will be created on behalf of the platform itself. example: Customer:019542f5-b3e7-1d02-0000-000000000009 currency: type: string description: Currency code for the funding source. See [Supported Currencies](https://docs.lightspark.com/platform-overview/core-concepts/currencies-and-rails) for the full list of supported fiat and crypto currencies. example: USD cryptoNetwork: type: string description: 'The crypto network to use for the funding source. Required when `currency` is a stablecoin (e.g. USDC, USDT). Specifies which network the customer will deposit on, so the correct deposit address can be generated. Example values: `SOLANA`, `ETHEREUM`, `BASE`, `POLYGON`, `TRON`, `PLASMA`, `ARBITRUM`, `SPARK`, `LIGHTNING`, `BITCOIN`.' example: SOLANA description: Fund the quote using a real-time funding source (RTP, SEPA Instant, Spark, Stables, etc.). This will require manual just-in-time funding using `paymentInstructions` in the response. Because quotes expire quickly, this option is only valid for instant payment methods. Do not try to fund a quote with a non-instant payment method (ACH, etc.). Currency: type: object properties: code: type: string description: Three-letter currency code (ISO 4217) for fiat currencies. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) example: USD name: type: string description: Full name of the currency example: United States Dollar symbol: type: string description: Symbol of the currency example: $ decimals: type: integer description: Number of decimal places for the currency minimum: 0 example: 2 PaymentEurAccountInfo: title: EUR Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EurAccountInfo' - type: object required: - reference properties: reference: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF CardMerchant: type: object required: - descriptor properties: descriptor: type: string description: Merchant descriptor string captured from the card network at authorization time. On the sandbox simulate endpoints, where this is supplied rather than reported, it must be 1–25 characters — the width of the card network's acceptor-name field. example: BLUE BOTTLE COFFEE SF mcc: type: string description: Merchant Category Code (ISO 18245) — four-digit numeric string. example: '5814' city: type: string description: Merchant city as reported by the card network, when present. example: San Francisco state: type: string description: Merchant state or region as reported by the card network, when present. example: CA country: type: string description: Two-letter ISO 3166-1 alpha-2 country code of the merchant. example: US PaymentPlasmaWalletInfo: title: Plasma Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/PlasmaWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDT TransactionType: type: string enum: - INCOMING - OUTGOING - CARD description: Type of transaction RailSelectionMode: type: string enum: - AUTO - MANUAL description: How the payment rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. example: AUTO CardTransaction: title: Card Transaction type: object required: - type - id - status - direction - merchant - authorizedAmount - accountId - customerId - platformCustomerId - authorizedAt - createdAt - updatedAt description: One row per cardholder-visible card transaction. A purchase row rolls its clearings up into `settledAmount`; a merchant return is its own dated `CREDIT` row linked back to the purchase via `originalTransactionId` rather than a rollup on the parent, so statements can list purchases and refunds as separate dated lines. Delivered whole as the `data` payload of every `CARD_TRANSACTION.*` webhook, and returned as the `CARD` variant of `Transaction` from `GET /transactions`. properties: type: type: string enum: - CARD description: Discriminator identifying this transaction as a card transaction in the `Transaction` list. id: type: string description: System-generated unique card transaction identifier example: Transaction:019542f5-b3e7-1d02-0000-000000000100 cardId: type: string description: The id of the `Card` this transaction was made on. example: Card:019542f5-b3e7-1d02-0000-000000000010 customerId: type: string description: System ID of the customer (cardholder) this transaction belongs to. example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific ID of the customer (cardholder) this transaction belongs to. example: 18d3e5f7b4a9c2 issuerTransactionToken: type: string description: Opaque identifier for the transaction on the underlying issuer. Used to cross-reference Grid records against issuer dashboards and webhooks. example: lithic_txn_b81c2a4f status: $ref: '#/components/schemas/CardTransactionStatus' cardDeclinedReason: $ref: '#/components/schemas/CardDeclinedReason' description: Present only when `status` is `DECLINED`. example: INSUFFICIENT_FUNDS direction: $ref: '#/components/schemas/TransactionDirection' description: A purchase is a `DEBIT`. A merchant refund is a `CREDIT` with the credited value in `settledAmount`; when the refund returns against a known purchase, `originalTransactionId` identifies it. example: DEBIT originalTransactionId: type: string description: 'On a refund row (`direction: CREDIT`), the id of the purchase this return credits back against. Absent on purchases and on standalone credits with no matching purchase.' example: Transaction:019542f5-b3e7-1d02-0000-000000000099 description: type: string description: The merchant descriptor, repeated from `merchant.descriptor` so a transaction list reads without expanding each card row. Unlike `description` on other transaction types, this is set by Grid from the card network's descriptor, not supplied by the platform. example: BLUE BOTTLE COFFEE SF merchant: $ref: '#/components/schemas/CardMerchant' authorizedAmount: $ref: '#/components/schemas/CurrencyAmount' settledAmount: $ref: '#/components/schemas/CurrencyAmount' refundedAmount: $ref: '#/components/schemas/CurrencyAmount' accountId: type: string description: Internal account id that funded this transaction (the funding source selected by Authorization Decisioning at auth time). example: InternalAccount:019542f5-b3e7-1d02-0000-000000000002 authorizedAt: type: string format: date-time description: When the authorization was approved or declined. example: '2026-05-08T14:30:00Z' createdAt: type: string format: date-time description: Creation timestamp (same as `authorizedAt` for card transactions). example: '2026-05-08T14:30:00Z' updatedAt: type: string format: date-time description: Last update timestamp. example: '2026-05-08T15:42:11Z' RtpRailDetails: title: RTP Transfer description: An instant payment over The Clearing House RTP network. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: type: string enum: - RTP status: $ref: '#/components/schemas/RtpRailStatus' endToEndId: type: string description: The originator's end-to-end reference for the payment. example: E2E-9f2c6b6f remittanceInformation: type: string description: Unstructured remittance information sent with the payment. example: INV-12345 FedNowRailDetails: title: FedNow Transfer description: An instant payment over the FedNow Service. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: type: string enum: - FEDNOW status: $ref: '#/components/schemas/FedNowRailStatus' endToEndId: type: string description: The originator's end-to-end reference for the payment. example: E2E-9f2c6b6f remittanceInformation: type: string description: Unstructured remittance information sent with the payment. example: INV-12345 BaseTransactionSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/TransactionSourceType' currency: type: string description: Currency code for the source example: USD AgentUsage: type: object description: Real-time counters tracking the agent's spending and transaction activity against its policy limits. required: - dailyTransactionCount - dailySpend - monthlySpend properties: dailyTransactionCount: type: integer description: Number of transactions initiated by the agent today. example: 3 dailySpend: type: integer description: Total amount spent by the agent today, in the smallest unit of the policy's `spendingLimits.currency`. example: 150000 dailyResetDate: type: string format: date description: The date when daily usage counters will reset. example: '2025-07-22' monthlySpend: type: integer description: Total amount spent by the agent this month, in the smallest unit of the policy's `spendingLimits.currency`. example: 750000 monthlyResetMonth: type: string description: The year-month (YYYY-MM) when monthly usage counters will reset. example: 2025-08 PaymentSolanaWalletInfo: title: Solana Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SolanaWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' MxnAccountInfo: allOf: - $ref: '#/components/schemas/MxnAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SPEI RealtimeFundingTransactionSource: title: External Funding Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - currency - sourceType properties: sourceType: type: string enum: - REALTIME_FUNDING customerId: type: string description: The customer on whose behalf the transaction was initiated. example: Customer:019542f5-b3e7-1d02-0000-000000000009 currency: type: string description: Currency code for the funding source example: USDC accountHolderName: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.accountHolderName`. The name of the originator (sender) of the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: John Sender accountIdentifier: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.accountNumber`. The originator's account number or IBAN. May be masked or partial depending on the rail. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '****6789' bankName: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.bankName` on wires. The name of the originating bank. Still populated on rails without a `railDetails` variant, such as SWIFT. example: Chase Bank bankIdentifier: type: string deprecated: true description: Deprecated. Use `railDetails.bankAccount.routingNumber`. The identifier of the originating bank, such as a routing number, BIC, or SWIFT code. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '021000021' paymentRail: deprecated: true description: Deprecated. Use `railDetails.paymentRail`. The payment rail the funds arrived on. Still populated on rails without a `railDetails` variant, such as SWIFT. allOf: - $ref: '#/components/schemas/PaymentRail' remittanceInformation: type: string deprecated: true description: Deprecated. Use `railDetails.addenda` for ACH, `railDetails.originatorToBeneficiaryInformation` for wires and `railDetails.remittanceInformation` for RTP and FedNow. Free-form information about the payment provided by the originator. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '12345' endToEndId: type: string deprecated: true description: Deprecated. Use `railDetails.endToEndId`. The originator's own end-to-end reference for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: E2E-9f2c6b6f traceNumber: type: string deprecated: true description: Deprecated. Use `railDetails.traceNumber` for ACH and `railDetails.imad` for wires. Rail-level tracking identifier for the payment. Still populated on rails without a `railDetails` variant, such as SWIFT. example: '021000020123456' railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Transaction was funded using an external funding source. `railDetails` describes the transfer that delivered the funds; its fields are populated on a best-effort basis depending on what the funding source provides. Rails without a `railDetails` variant, such as SWIFT, carry the originator's details in the deprecated flat fields only. IncomingTransaction: title: Incoming Transaction allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - type properties: type: type: string enum: - INCOMING source: $ref: '#/components/schemas/TransactionSourceOneOf' receivedAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount received in the recipient's currency. This is only absent for rule-based account sweeps if the sweep couldn't be quoted. It's always present otherwise. fees: type: integer format: int64 description: The total fees available from the receive quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Included for all transactions except those with "CREATED" status failureReason: $ref: '#/components/schemas/IncomingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. EthereumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ETHEREUM_WALLET address: type: string description: Ethereum L1 wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' Error500: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | GRID_SWITCH_ERROR | Grid switch error | | INTERNAL_ERROR | Internal server or UMA error | ' enum: - GRID_SWITCH_ERROR - INTERNAL_ERROR reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true UmaAddressTransactionSource: title: UMA Address Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - umaAddress - sourceType properties: sourceType: type: string enum: - UMA_ADDRESS umaAddress: type: string description: UMA address of the sender example: $sender@uma.domain.com description: UMA address source details PaymentAccountType: type: string enum: - USD_ACCOUNT - BRL_ACCOUNT - MXN_ACCOUNT - DKK_ACCOUNT - ARS_ACCOUNT - COP_ACCOUNT - EUR_ACCOUNT - INR_ACCOUNT - NGN_ACCOUNT - CAD_ACCOUNT - GBP_ACCOUNT - HKD_ACCOUNT - IDR_ACCOUNT - MYR_ACCOUNT - PHP_ACCOUNT - SGD_ACCOUNT - THB_ACCOUNT - VND_ACCOUNT - SWIFT_ACCOUNT - SPARK_WALLET - LIGHTNING - SOLANA_WALLET - TRON_WALLET - PLASMA_WALLET - ARBITRUM_WALLET - POLYGON_WALLET - BASE_WALLET - ETHEREUM_WALLET - EMBEDDED_WALLET - BITCOIN_L1 description: Type of payment account or wallet example: USD_ACCOUNT RefundStatus: type: string enum: - PENDING - COMPLETED - FAILED description: Current status of the refund example: COMPLETED ScaFactor: type: string enum: - SMS_OTP - TOTP - PASSKEY description: 'A Strong Customer Authentication factor. | Factor | Description | |--------|-------------| | `SMS_OTP` | One-time code sent by SMS to the customer''s verified phone. Requires no prior enrollment. | | `TOTP` | Time-based one-time code from an authenticator app. Requires enrollment. Not valid for per-transaction challenges (cannot carry dynamic linking). | | `PASSKEY` | WebAuthn passkey assertion. Requires enrollment. | ' AgentDeviceCodeRedeemResponse: type: object required: - agentId - agentName - accessToken - policy properties: agentId: type: string description: The agent's system-generated ID. example: Agent:019542f5-b3e7-1d02-0000-000000000001 agentName: type: string description: The agent's name. example: Payroll Automation Agent accessToken: type: string description: 'Bearer token used to authenticate all subsequent API calls as this agent. Pass as `Authorization: Bearer `. This token is returned only once and must be stored securely — it cannot be retrieved again.' example: gat_ed0ad25881e234cc28fb2dec0a4fe64e4172a3b9 policy: $ref: '#/components/schemas/AgentPolicy' FieldConstraint: type: object description: Machine-readable validator hint accompanying a 400 `INVALID_INPUT` error. Consumers use it to drive form UI (input types, dropdowns, masking, length limits) and to pre-validate the field client-side before re-submitting. Fields are additive. properties: format: type: string description: Named format the value must satisfy — HTML5 input type names (`email`, `tel`, `url`, `date`, ...) or semantic slugs (`iso3166-1-alpha-2`, `bcp47-language-tag`, `us-ssn`, `e.164`). example: email pattern: type: string description: Regular expression the value must match (JavaScript-flavor). example: ^\d{5}(-\d{4})?$ enum: type: array items: type: string description: Allowed values when the field is drawn from a fixed set. example: - SSN - ITIN - NON_US_TAX_ID minLength: type: integer description: Minimum length in characters. example: 1 maxLength: type: integer description: Maximum length in characters. example: 500 Quote: type: object required: - id - status - expiresAt - createdAt - source - destination - sendingCurrency - receivingCurrency - totalSendingAmount - totalReceivingAmount - exchangeRate - feesIncluded - transactionId properties: id: type: string description: Unique identifier for this quote example: Quote:019542f5-b3e7-1d02-0000-000000000006 status: $ref: '#/components/schemas/QuoteStatus' createdAt: type: string format: date-time description: When this quote was created example: '2025-10-03T12:00:00Z' expiresAt: type: string format: date-time description: '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: $ref: '#/components/schemas/QuoteSourceOneOf' destination: $ref: '#/components/schemas/QuoteDestinationOneOf' sendingCurrency: $ref: '#/components/schemas/Currency' description: Currency for the sending amount receivingCurrency: $ref: '#/components/schemas/Currency' description: Currency for the receiving amount totalSendingAmount: type: integer format: int64 description: The total amount that will be sent in the smallest unit of the sending currency (eg. cents). exclusiveMinimum: 0 example: 123010 totalReceivingAmount: type: integer format: int64 description: The total amount that will be received in the smallest unit of the receiving currency (eg. cents). exclusiveMinimum: 0 example: 1000 exchangeRate: type: number description: '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`.' exclusiveMinimum: 0 feesIncluded: type: integer format: int64 description: '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.' minimum: 0 example: 10 platformFeesIncluded: type: integer format: int64 description: 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. minimum: 0 example: 5 paymentInstructions: type: array description: Payment instructions for executing the payment. This is not required when using an internal account source. items: $ref: '#/components/schemas/PaymentInstructions' 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 transactionId: type: string description: The ID of the transaction created from this quote. example: Transaction:019542f5-b3e7-1d02-0000-000000000005 counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' description: Additional information about the counterparty, if available and required by the platform in their configuration. rateDetails: $ref: '#/components/schemas/OutgoingRateDetails' description: Details about the rate and fees for the transaction. purposeOfPayment: $ref: '#/components/schemas/PurposeOfPayment' description: The purpose of payment the quote was created with. Present only when the quote request set `purposeOfPayment`. documentIds: type: array description: 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. items: type: string example: - PaymentDocument:019542f5-b3e7-1d02-0000-000000000001 - PaymentDocument:019542f5-b3e7-1d02-0000-000000000002 - PaymentDocument:019542f5-b3e7-1d02-0000-000000000003 scaChallenge: $ref: '#/components/schemas/ScaChallenge' description: '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).' AchRailStatus: type: string enum: - PENDING - SETTLED - RETURNED - RETURN_DISHONORED - RETURN_CONTESTED - REVERSED - FAILED description: 'Status of the entry on the ACH network. | Status | Description | |--------|-------------| | `PENDING` | Submitted to the ACH network and not yet settled. | | `SETTLED` | The entry settled. | | `RETURNED` | The receiving bank returned the entry, before or after it settled. | | `RETURN_DISHONORED` | The originating bank dishonored the return, so the returned funds came back. | | `RETURN_CONTESTED` | The receiving bank contested the dishonor, so the funds went back again. | | `REVERSED` | The originator reversed the entry after it settled. | | `FAILED` | The entry was rejected before submission and no funds moved. | A return, dishonor or contest can arrive days after the step before it. This status reports the ACH entry; the transaction''s top-level `status` reports where the funds are now. A return moves the transaction to `FAILED`. On an incoming payment, a dishonor brings the credit back and moves it to `COMPLETED`, and a contest moves it to `FAILED` again. A returned payout stays `FAILED` through a dishonor, since it has already been refunded; the rail status still records the dishonor.' example: SETTLED OutgoingTransactionStatus: type: string enum: - PENDING - PENDING_AUTHORIZATION - EXPIRED - PROCESSING - COMPLETED - FAILED description: 'Status of an outgoing payment transaction. | Status | Description | |--------|-------------| | `PENDING` | Quote is pending confirmation | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction''s `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `EXPIRED` | Quote wasn''t executed before expiry window. Terminal | | `PROCESSING` | Executing the quote after receiving funds | | `COMPLETED` | The funds are at the destination. A bank return moves the payout to `FAILED` | | `FAILED` | The payout did not reach the destination, or was returned after it did — accompanied by a `failureReason`, and refunded to the source. A returned payout stays `FAILED` even if the return is later dishonored, since the refund has already been posted; the dishonor shows on `destination.railDetails` | ' AgentActionListResponse: type: object required: - data - hasMore properties: data: type: array description: List of agent actions matching the filter criteria. items: $ref: '#/components/schemas/AgentAction' hasMore: type: boolean description: Indicates if more results are available beyond this page. nextCursor: type: string description: Cursor to retrieve the next page of results (only present if hasMore is true). totalCount: type: integer description: Total number of actions matching the criteria (excluding pagination). IncomingTransactionFailureReason: type: string enum: - LNURLP_FAILED - PAY_REQUEST_FAILED - PAYMENT_APPROVAL_WEBHOOK_ERROR - PAYMENT_APPROVAL_TIMED_OUT - OFFRAMP_FAILED - MISSING_MANDATORY_PAYEE_DATA - QUOTE_EXPIRED - QUOTE_EXECUTION_FAILED - COMPLIANCE_REJECTED - COLLECTION_FAILED - SWEEP_AMOUNT_OUT_OF_RANGE - SWEEP_QUOTE_FAILED description: 'Reason for failure of an incoming transaction. This is used to provide more context on why a transaction failed. If the transaction is not in a failed state, this field is omitted. COMPLIANCE_REJECTED means compliance blocked the incoming funds. COLLECTION_FAILED means an inbound bank-rail collection deposit (e.g. a SWIFT wire) failed after arrival and did not credit — most commonly a compliance-screening rejection or an unresolved request for information, on either the collection provider''s side or Grid''s. Failed collections are returned to the sender per the collection provider''s process. A payment that settled into a rule-based account but could not be swept to the destination of the account''s rule fails with one of the `SWEEP_*` reasons. A rule-based account never holds a balance, so the funds are moved to the account holder''s own account in the same currency. SWEEP_AMOUNT_OUT_OF_RANGE means the amount was outside the band the corridor to the destination can carry — the rule''s minimumAmount and maximumAmount give the current band — and SWEEP_QUOTE_FAILED that Grid could not price it. A sweep that was priced and then failed on the way to settlement reports QUOTE_EXECUTION_FAILED, the same as any other payment.' Error404: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | TRANSACTION_NOT_FOUND | Transaction not found | | INVITATION_NOT_FOUND | Invitation not found | | USER_NOT_FOUND | Customer not found | | QUOTE_NOT_FOUND | Quote not found | | LOOKUP_REQUEST_NOT_FOUND | Lookup request not found | | TOKEN_NOT_FOUND | Token not found | | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found | | REFERENCE_NOT_FOUND | Reference not found | | UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP | | STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND | Stablecoin provider account link not found | | ACCOUNT_NOT_FOUND | Account not found | | AUTH_METHOD_NOT_FOUND | Authentication credential not found | | CUSTOMER_NOT_FOUND | Customer not found | | DOCUMENT_HOLDER_NOT_FOUND | Document holder not found | | NOT_FOUND | The requested resource was not found | | PAYMENT_URL_NOT_FOUND | Payment URL not found | | PLATFORM_NOT_FOUND | Platform not found | | REQUEST_NOT_FOUND | Pending request not found | | SESSION_NOT_FOUND | Session not found | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND | Stablecoin external account not found | | STABLECOIN_NOT_FOUND | Stablecoin not found | | STABLECOIN_OPERATION_NOT_FOUND | Stablecoin operation not found | | VERIFICATION_NOT_FOUND | Verification not found | | PAYMENT_DOCUMENT_NOT_FOUND | Payment document not found | ' enum: - TRANSACTION_NOT_FOUND - INVITATION_NOT_FOUND - USER_NOT_FOUND - QUOTE_NOT_FOUND - LOOKUP_REQUEST_NOT_FOUND - TOKEN_NOT_FOUND - BULK_UPLOAD_JOB_NOT_FOUND - REFERENCE_NOT_FOUND - UMA_NOT_FOUND - STABLECOIN_PROVIDER_ACCOUNT_NOT_FOUND - ACCOUNT_NOT_FOUND - AUTH_METHOD_NOT_FOUND - CUSTOMER_NOT_FOUND - DOCUMENT_HOLDER_NOT_FOUND - NOT_FOUND - PAYMENT_URL_NOT_FOUND - PLATFORM_NOT_FOUND - REQUEST_NOT_FOUND - SESSION_NOT_FOUND - STABLECOIN_EXTERNAL_ACCOUNT_NOT_FOUND - STABLECOIN_NOT_FOUND - STABLECOIN_OPERATION_NOT_FOUND - VERIFICATION_NOT_FOUND - PAYMENT_DOCUMENT_NOT_FOUND reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true AgentSpendingLimitsUpdate: type: object description: Partial update to spending limits. Only provided fields will be updated; omitted fields retain their current values. properties: currency: type: string description: ISO 4217 currency code that all amount limits are denominated in. If supplied, it must equal the existing policy currency; changing it returns a 400 response. example: USD perTransactionLimit: type: integer description: Maximum amount per transaction. example: 50000 dailyLimit: type: - integer - 'null' description: Maximum daily spend. Set to null to remove the daily limit. example: 500000 dailyTransactionLimit: type: integer description: Maximum number of transactions per day. example: 10 monthlyLimit: type: - integer - 'null' description: Maximum monthly spend. Set to null to remove the monthly limit. example: 5000000 RtpRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: 'Status of the payment on the RTP network. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank''s response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. |' example: SETTLED AgentAccountRule: type: object description: Per-account policy override that takes precedence over the agent's default policy for a specific account. required: - accountId properties: accountId: type: string description: The internal account ID this rule applies to. example: Account:019542f5-b3e7-1d02-0000-000000000001 executionMode: $ref: '#/components/schemas/AgentExecutionMode' perTransactionLimit: type: - integer - 'null' description: Per-transaction limit override, in the smallest unit of the policy's `spendingLimits.currency`. Null inherits from the agent's spending limits. example: 10000 Transaction: type: object required: - id - status - type - direction - destination - customerId - platformCustomerId properties: id: type: string description: Unique identifier for the transaction example: Transaction:019542f5-b3e7-1d02-0000-000000000004 status: $ref: '#/components/schemas/TransactionStatus' pendingReason: $ref: '#/components/schemas/TransactionPendingReason' description: Present when compliance review or required customer action is delaying settlement. type: $ref: '#/components/schemas/TransactionType' direction: $ref: '#/components/schemas/TransactionDirection' description: Whether this transaction credits or debits the customer's account. destination: $ref: '#/components/schemas/TransactionDestinationOneOf' ruleBasedAccountId: type: string description: The `RULE_BASED` internal account whose deposit this transaction sweeps. Present only on sweep transactions. For these, `source` describes the party that made the deposit when it is known, and is this account otherwise. example: InternalAccount:019542f5-b3e7-1d02-0000-000000000011 customerId: type: string description: System ID of the customer this transaction belongs to example: Customer:019542f5-b3e7-1d02-0000-000000000001 platformCustomerId: type: string description: Platform-specific ID of the customer this transaction belongs to example: 18d3e5f7b4a9c2 settledAt: type: string format: date-time description: When the payment was or will be settled example: '2025-08-15T14:30:00Z' createdAt: type: string format: date-time description: When the transaction was created example: '2025-08-15T14:25:18Z' updatedAt: type: string format: date-time description: When the transaction was last updated example: '2025-08-15T14:30:00Z' receiptDeliveryConfirmedAt: type: string format: date-time description: The time at which the platform confirmed delivery of the receipt to their customer. example: '2025-08-15T14:31:00Z' agentId: type: string description: If this transaction was initiated by an agent, the system-generated ID of that agent. Absent for platform-initiated transactions. example: Agent:019542f5-b3e7-1d02-0000-000000000042 description: type: string description: Optional memo or description for the payment example: 'Payment for invoice #1234' sentAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount sent in the sender's currency exchangeRate: type: number description: 'Number of sending currency units per receiving currency unit. The rate is fee-exclusive: Grid deducts fees from the sending amount before converting at this rate.' exclusiveMinimum: 0 example: 1.08 quoteId: type: string description: The ID of the quote that was used to trigger this payment example: Quote:019542f5-b3e7-1d02-0000-000000000006 refund: $ref: '#/components/schemas/Refund' description: The refund if transaction was refunded. counterpartyInformation: $ref: '#/components/schemas/CounterpartyInformation' PaymentDocumentRequirementId: type: string description: 'A stable identifier for one required document within a purpose''s requirements. The same ID means the same requirement across quotes. It is separate from `PaymentDocumentType`. The requirement ID names the document to supply, and the document type names what a file is. The two differ where a requirement accepts alternatives. For example, a file declared as either `PURCHASE_ORDER` or `DELIVERY_SLIP` fills the `SUPPORTING_PROOF` requirement. [Supporting Documents](https://docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment#supporting-documents) lists the IDs each purpose requires. Treat the ID as an opaque value, not a member of a fixed list. Grid may add new IDs as requirements change.' example: SUPPORTING_PROOF PaymentArbitrumWalletInfo: title: Arbitrum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/ArbitrumWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' EurAccountInfo: allOf: - $ref: '#/components/schemas/EurAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SEPA - SEPA_INSTANT PaymentBaseWalletInfo: title: Base Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/BaseWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDC OutgoingTransaction: title: Outgoing Transaction allOf: - $ref: '#/components/schemas/Transaction' - type: object required: - type - sentAmount - source properties: status: $ref: '#/components/schemas/OutgoingTransactionStatus' type: type: string enum: - OUTGOING source: $ref: '#/components/schemas/TransactionSourceOneOf' sentAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount sent in the sender's currency receivedAmount: $ref: '#/components/schemas/CurrencyAmount' description: Amount to be received by recipient in the recipient's currency fees: type: integer format: int64 description: The fees associated with the quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 platformFees: type: integer format: int64 description: The portion of `fees` 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 `fees`. minimum: 0 example: 5 reconciliationInstructions: $ref: '#/components/schemas/ReconciliationInstructions' description: Reconciliation details for this transaction. For the on-chain hash of a crypto payout to an external wallet, see the destination's `railDetails` instead. paymentInstructions: type: array description: Payment instructions for executing the payment. items: $ref: '#/components/schemas/PaymentInstructions' 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 rateDetails: $ref: '#/components/schemas/OutgoingRateDetails' description: Details about the rate and fees for the transaction. failureReason: $ref: '#/components/schemas/OutgoingTransactionFailureReason' description: If the transaction failed, this field provides the reason for failure. paymentRail: anyOf: - $ref: '#/components/schemas/PaymentRail' - type: 'null' description: The payment rail used to settle this transaction (e.g. ACH, WIRE, NEFT, FASTER_PAYMENTS). Uses the same values as the PaymentRail sent on quote requests. Null when no external rail is used (e.g. instant or intra-network transfers, or non-direct-destination transactions) or before a rail is resolved. railSelectionMode: $ref: '#/components/schemas/RailSelectionMode' description: How the rail was chosen — MANUAL when the platform specified a paymentRail on the destination, AUTO when Lightspark selects it. expectedSettlementAt: type: - string - 'null' format: date-time description: Expected settlement time at the beneficiary. Null for instant rails (settlement is immediate) and before a rail with deferred settlement is resolved. settlementTimelineSeconds: type: - integer - 'null' description: Expected number of seconds from quote creation to settlement. Null when not yet known. AgentChainAddressDestination: title: Chain Address type: object required: - destinationType - network - currency - address properties: destinationType: type: string enum: - CHAIN_ADDRESS description: Marks a destination on another chain. example: CHAIN_ADDRESS network: $ref: '#/components/schemas/AgentSendNetwork' description: Network the recipient receives on. example: BASE currency: $ref: '#/components/schemas/AgentSendCurrency' description: 'Asset the recipient receives: `USDC` or `USDT`. `TRON` supports `USDT` only, and `BASE` supports `USDC` only.' example: USDC address: type: string maxLength: 128 description: Recipient address on `network`. example: '0x1234567890abcdef1234567890abcdef12345678' description: An address on another chain, paid from an `EMBEDDED_WALLET` holding `USDB`. Grid records the address as an external account of the agent's customer, reusing the account when the customer already has one for the same network, currency and address, and screens it before quoting. The quote's `destination` names that account. BaseUsdBankRailDetails: title: Base US Bank Rail Details type: object description: Fields shared by every US bank rail. properties: bankAccount: $ref: '#/components/schemas/UsdBankAccountDetails' settledAt: type: string format: date-time description: When the transfer settled. example: '2026-09-29T15:04:12Z' AgentAccountRestrictions: type: object description: Optional restrictions that limit the agent to specific accounts or override policy per account. properties: allowedAccountIds: type: - array - 'null' description: If set, restricts the agent to operate only on the specified internal account IDs. Null means the agent can access all accounts. items: type: string example: Account:019542f5-b3e7-1d02-0000-000000000001 accountRules: type: array description: Per-account rules that override the agent's default policy for specific accounts. items: $ref: '#/components/schemas/AgentAccountRule' PaymentBitcoinDepositAddressInfo: title: Bitcoin L1 Deposit Address allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - address properties: accountType: type: string enum: - BITCOIN_L1 address: type: string description: On-chain Bitcoin (L1) deposit address to send funds to example: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq network: type: string description: The blockchain network for the deposit address. enum: - BITCOIN example: BITCOIN BaseQuoteSource: type: object required: - sourceType properties: sourceType: $ref: '#/components/schemas/QuoteSourceType' AgentSpendingLimits: type: object description: Spending limits that cap the agent's transaction amounts and frequency. All amount fields are integers in the smallest unit of the specified currency. When a transaction is denominated in a different currency, Grid converts using the exchange rate at evaluation time. required: - currency - perTransactionLimit properties: currency: type: string description: ISO 4217 currency code that all amount limits are denominated in. This currency is immutable after the agent is created. example: USD perTransactionLimit: type: integer description: Maximum amount the agent can transfer in a single transaction. example: 50000 dailyLimit: type: - integer - 'null' description: Maximum total amount the agent can transfer per day. Null means no daily limit. example: 500000 dailyTransactionLimit: type: integer description: Maximum number of transactions the agent can initiate per day. example: 10 monthlyLimit: type: - integer - 'null' description: Maximum total amount the agent can transfer per month. Null means no monthly limit. example: 5000000 AchRailDetails: title: ACH Transfer description: A transfer over the ACH network. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: paymentRail: $ref: '#/components/schemas/AchPaymentRail' status: $ref: '#/components/schemas/AchRailStatus' traceNumber: type: string description: 15-digit ACH trace number of the entry. example: '021000020123456' statementDescriptor: type: string maxLength: 10 description: The entry's Company Entry Description, which the receiving bank shows on the account holder's statement. On payments you originate, this is the quote's `statementDescriptor`, or Grid's default. example: PAYROLL addenda: type: string description: Payment-related text carried in the entry's addenda record. On payments you originate, this is the `remittanceInformation` you provided. example: INV-12345 returnedAt: type: string format: date-time description: When the receiving bank returned the entry. Present once the entry has been returned, including after a later dishonor or contest. example: '2026-10-01T14:00:00Z' dishonoredAt: type: string format: date-time description: When the originating bank dishonored the return. Present once `status` has reached `RETURN_DISHONORED`. example: '2026-10-04T14:00:00Z' contestedAt: type: string format: date-time description: When the receiving bank contested the dishonor. Present when `status` is `RETURN_CONTESTED`. example: '2026-10-07T14:00:00Z' reversedAt: type: string format: date-time description: When the originator reversed the entry. Present when `status` is `REVERSED`. example: '2026-10-01T14:00:00Z' AgentDeviceCode: type: object required: - code - agentId - expiresAt - redeemed properties: code: type: string description: 'Device code used to install and connect the agent software: an opaque 22-character URL-safe base64 string encoding 128 random bits. It is returned only when it is issued, because Grid stores only a hash of it; if it is lost before it is redeemed, regenerate it. It can be redeemed once.' example: jqzJR3AgI9OAwb_enypARw agentId: type: string description: The agent this device code belongs to. example: Agent:019542f5-b3e7-1d02-0000-000000000001 expiresAt: type: string format: date-time description: Timestamp when this device code expires. Codes expire 15 minutes after they are issued by default; Grid can configure a platform's lifetime between 1 and 60 minutes. example: '2025-07-22T17:32:28Z' redeemed: type: boolean description: Whether this device code has already been redeemed by the agent. example: false TransactionOneOf: oneOf: - $ref: '#/components/schemas/IncomingTransaction' - $ref: '#/components/schemas/OutgoingTransaction' - $ref: '#/components/schemas/CardTransaction' discriminator: propertyName: type mapping: INCOMING: '#/components/schemas/IncomingTransaction' OUTGOING: '#/components/schemas/OutgoingTransaction' CARD: '#/components/schemas/CardTransaction' AgentSendNetwork: type: string enum: - BASE - ETHEREUM - SOLANA - POLYGON - ARBITRUM - TRON description: Network an agent can send USDC or USDT to from an embedded wallet. `TRON` supports `USDT` only, and `BASE` supports `USDC` only. AgentPolicyUpdateRequest: type: object description: Partial update to an agent's policy. Only provided fields will be updated; omitted fields retain their current values. properties: permissions: type: array description: Updated list of permissions. Replaces the entire permissions list when provided. items: $ref: '#/components/schemas/AgentPermission' defaultExecutionMode: $ref: '#/components/schemas/AgentExecutionMode' spendingLimits: $ref: '#/components/schemas/AgentSpendingLimitsUpdate' accountRestrictions: $ref: '#/components/schemas/AgentAccountRestrictions' approvalThresholds: $ref: '#/components/schemas/AgentApprovalThresholds' AgentActionRejectRequest: type: object properties: reason: type: string description: Optional human-readable reason for the rejection, stored on the action and visible to the platform. example: Transaction amount exceeds customer's current risk limit. CardDeclinedReason: type: string enum: - CARD_NOT_ACTIVE - SPEND_LIMIT_EXCEEDED - INSUFFICIENT_FUNDS - NO_ELIGIBLE_FUNDING_SOURCE - BLOCKED - UNSUPPORTED_NETWORK - INCORRECT_CARD_DETAILS - TEMPORARILY_UNAVAILABLE - OTHER description: 'Why Grid declined a card authorization. Present only when a card transaction''s `status` is `DECLINED`. | Reason | Returned when | |--------|---------------| | `CARD_NOT_ACTIVE` | The card is not `ACTIVE`. A `FROZEN`, `PROCESSING`, `PENDING_KYC`, or `CLOSED` card declines every authorization. | | `SPEND_LIMIT_EXCEEDED` | The authorization exceeds `maxSpendPerTransaction`, `maxSpendPerDay`, `maxTransactionsPerDay`, or the matching platform cap. | | `INSUFFICIENT_FUNDS` | The funding source balance does not cover the authorization. Grid reserves the amount when it decides the authorization, so an underfunded card is declined. | | `NO_ELIGIBLE_FUNDING_SOURCE` | The card has no usable funding source, for example an Embedded Wallet source with no active delegated key. | | `BLOCKED` | Program rules block the merchant category or the transaction. | | `UNSUPPORTED_NETWORK` | Grid does not support the network or the transaction type. | | `INCORRECT_CARD_DETAILS` | The PIN, security code, expiry date, or billing address entered at the merchant did not match the card. | | `TEMPORARILY_UNAVAILABLE` | A temporary problem at Grid, the card processor, or the card network stopped the authorization. The cardholder can try again. | | `OTHER` | Any other reason, including a security or fraud decline the card processor made. | ' CurrencyAmount: type: object required: - amount - currency properties: amount: type: integer format: int64 description: Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC) example: 12550 currency: $ref: '#/components/schemas/Currency' PaymentEmbeddedWalletInfo: title: Embedded Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - accountType - payloadToSign properties: accountType: type: string enum: - EMBEDDED_WALLET description: Discriminator value identifying this as Embedded Wallet payment instructions. payloadToSign: type: string description: JSON-encoded transaction signing payload that must be stamped, as-is (byte-for-byte, without re-serialization), with the session private key of a verified authentication credential on the source Embedded Wallet. The resulting Grid wallet signature is passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet. example: '{"type":"ACTIVITY_TYPE_SIGN_TRANSACTION_V2","timestampMs":"1746736509954","organizationId":"org_abc123","parameters":{"signWith":"wallet_abc123def456","unsignedTransaction":"ea69b4bf05f775209f26ff0a34a05569180f7936579d5c4af9377ae550194f72","type":"TRANSACTION_TYPE_ETHEREUM"},"generateAppProofs":true}' TransactionSourceType: type: string enum: - ACCOUNT - UMA_ADDRESS - REALTIME_FUNDING description: Type of transaction source example: ACCOUNT PaymentRail: type: string enum: - ACH - ACH_COLOMBIA - ACH_SAME_DAY - BANK_TRANSFER - BRE_B - CIPS - FAST - FASTER_PAYMENTS - FEDNOW - INSTAPAY - MOBILE_MONEY - NEFT - PAYNOW - PESONET - PIX - RTGS - RTP - SEPA - SEPA_INSTANT - SPEI - SWIFT - UNIONPAY - UPI - WIRE description: 'The payment rail used for the transfer. Payment rails represent the underlying payment network or system used to move funds between accounts. `ACH_SAME_DAY` requests same-business-day settlement for a USD payout and is priced separately. It is subject to the NACHA per-entry same-day limit, which the network applies to every originator: $1,000,000 per entry, rising to $10,000,000 on 2027-09-17. A payout above that limit is rejected rather than slowed — check the amount before requesting this rail, or send it over `ACH`, which settles on the standard schedule and has no such limit. `ACH` will settle on the standard next-business-day schedule. Until a date we announce in advance, `ACH` continues to settle same-business-day on production platforms; it already settles next-business-day on sandbox platforms. To guarantee same-day settlement after that date, request `ACH_SAME_DAY`.' example: ACH OutgoingRateDetails: description: 'Details about the rate and fees for an outgoing transaction or quote. Note: `counterpartyFixedFee` is denominated in the receiving currency, so its equivalent value in the sending currency fluctuates with the FX rate. As a result, the total fee on a subsequent quote for the same transfer may differ even if the underlying fee structure is unchanged.' type: object required: - counterpartyMultiplier - counterpartyFixedFee - gridApiMultiplier - gridApiFixedFee - gridApiVariableFeeRate - gridApiVariableFeeAmount properties: counterpartyMultiplier: type: number format: double description: The underlying multiplier from mSATs to the receiving currency as returned by the counterparty institution. exclusiveMinimum: 0 example: 1.08 counterpartyFixedFee: type: integer format: int64 description: The fixed fee charged by the counterparty institution to execute the quote in the smallest unit of the receiving currency (eg. cents). minimum: 0 example: 10 gridApiMultiplier: type: number format: double description: The underlying multiplier from the sending currency to mSATS, including variable fees. exclusiveMinimum: 0 example: 0.925 gridApiFixedFee: type: integer format: int64 description: The fixed fee charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). minimum: 0 example: 10 gridApiVariableFeeRate: type: number format: double description: The variable fee rate charged by the Grid product to execute the quote as a percentage of the sending currency amount. minimum: 0 example: 0.003 gridApiVariableFeeAmount: type: number format: int64 description: The variable fee amount charged by the Grid product to execute the quote in the smallest unit of the sending currency (eg. cents). This is the sending amount times gridApiVariableFeeRate. minimum: 0 example: 30 ArbitrumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ARBITRUM_WALLET address: type: string description: Arbitrum wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' QuoteStatus: type: string enum: - PENDING - PENDING_AUTHORIZATION - PROCESSING - COMPLETED - FAILED - EXPIRED description: '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.' example: PENDING PolygonWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - POLYGON_WALLET address: type: string description: Polygon eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' OnChainRailDetails: title: On-Chain Transfer type: object required: - paymentRail - transactionHash - network properties: paymentRail: type: string enum: - ONCHAIN transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). description: A crypto transfer to or from an external wallet. TronWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - TRON_WALLET address: type: string description: Tron wallet address example: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL PaymentUsdAccountInfo: title: USD Bank Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/UsdAccountInfo' - type: object required: - reference properties: reference: type: string description: Unique reference code that must be included with the payment to properly credit it example: UMA-Q12345-REF bankAddress: type: string description: The postal address of the financial institution holding the account, on a single line. Optional on every rail, and recommended for wires, where some originating banks require the beneficiary institution's address before they will send. example: 885 Teaneck Road, Teaneck, NJ 07666 minLength: 1 maxLength: 255 Error409: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL | Transaction is not pending platform approval | | TRANSACTION_NOT_CANCELLABLE | Transaction has already settled or is otherwise past the point where it can be cancelled | | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another | | SCA_SESSION_REQUIRED | The customer''s Strong Customer Authentication login session is missing or expired. Re-authenticate the customer, then retry the request. Distinct from a `401`, which means the platform''s own API credentials were rejected | | BENEFICIARY_TRUSTED | The external account is currently a trusted beneficiary, so it cannot be deleted. Untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete | | BANK_ACCOUNT_VALIDATION_PENDING | The US bank account on this request is still being validated. Grid verifies a newly added ACH account by sending a micro-entry and waiting out the return window, which takes a few banking days. The account is not rejected; retry once validation completes. A permanently failed account returns `400 INVALID_BANK_ACCOUNT` instead | | INVALID_STATE_TRANSITION | The requested card `status` transition is not one of `ACTIVE ⇄ FROZEN` or `ACTIVE \| FROZEN → CLOSED`, or the card cannot be unfrozen by the platform because Grid froze it for review, it was frozen as `COMPROMISED`, or its customer is not `ACTIVE` | | CARD_ALREADY_CLOSED | `status: CLOSED` was requested for a card that is already `CLOSED` | | CARD_NOT_MUTABLE | The card is `CLOSED`, so it can no longer be mutated | | PIN_CHANGE_REQUIRED | The card''s PIN unblock allowance is consumed for seven days. Change the PIN to recover sooner. `details.pinUnblockAvailableAt` gives the next allowed unblock time | | CARD_LIMIT_REACHED | The platform has reached the maximum number of live cards it may hold, or the cardholder already holds a card and the platform is limited to one per cardholder. Closing a card frees its slot; contact Lightspark to raise the limit | | STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE | Grid enablement can only be requested while the stablecoin is `NOT_ENABLED` (a repeat request while already `PENDING_APPROVAL` succeeds). `ENABLING`, `ENABLED` and `DISABLED` are driven by Lightspark and cannot be requested | | NOT_YET_AVAILABLE | The request is valid, but its result is not available yet because the data it depends on could still change. Retry later. `reason` says what is outstanding. For balance changes, card settlement for a window boundary has not closed | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform | | DOCUMENT_ALREADY_EXISTS | A document of this type already exists for the holder; replace it with PUT | | DUPLICATE_EXTERNAL_ACCOUNT | An equivalent external account already exists. When the conflicting account belongs to your platform, `details.externalAccountId` and `details.platformAccountId` identify it; otherwise `details` is omitted | | DUPLICATE_PAY_REQUEST | A pay request with this idempotency key already exists | | OPERATION_IN_PROGRESS | A conflicting Embedded Wallet operation is still in progress | | SMS_OTP_CREDENTIAL_SET_CHANGED | The SMS_OTP credential set changed while the request was in flight | | SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS | The phone number is already associated with an SMS_OTP credential | | STABLECOIN_SYMBOL_ALREADY_EXISTS | A stablecoin with this symbol is already registered | | STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS | A stablecoin with this token identifier is already registered | | WALLET_NOT_PROVISIONED | The embedded wallet has not been provisioned | | PAYMENT_DOCUMENT_ALREADY_USED | The payment document is already attached to a quote. A document can be used on one quote only, so upload the file again to use it on another quote | ' enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL - TRANSACTION_NOT_CANCELLABLE - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED - BENEFICIARY_TRUSTED - BANK_ACCOUNT_VALIDATION_PENDING - INVALID_STATE_TRANSITION - CARD_ALREADY_CLOSED - CARD_NOT_MUTABLE - PIN_CHANGE_REQUIRED - CARD_LIMIT_REACHED - STABLECOIN_GRID_ENABLEMENT_NOT_REQUESTABLE - NOT_YET_AVAILABLE - CONFLICT - DOCUMENT_ALREADY_EXISTS - DUPLICATE_EXTERNAL_ACCOUNT - DUPLICATE_PAY_REQUEST - OPERATION_IN_PROGRESS - SMS_OTP_CREDENTIAL_SET_CHANGED - SMS_OTP_PHONE_NUMBER_ALREADY_EXISTS - STABLECOIN_SYMBOL_ALREADY_EXISTS - STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS - WALLET_NOT_PROVISIONED - PAYMENT_DOCUMENT_ALREADY_USED reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true TransactionStatus: type: string enum: - CREATED - PENDING - PENDING_AUTHORIZATION - PROCESSING - COMPLETED - REJECTED - FAILED - REFUNDED - EXPIRED description: 'Status of a payment transaction. | Status | Description | |--------|-------------| | `CREATED` | Initial lookup has been created | | `PENDING` | Quote has been created | | `PENDING_AUTHORIZATION` | Awaiting Strong Customer Authentication. Only occurs for customers in a region where SCA is required (e.g. EU). The challenge is carried by the quote, not the transaction — fetch `GET /quotes/{quoteId}` using the transaction''s `quoteId`, then authorize its `scaChallenge` via `POST /quotes/{quoteId}/authorize`. | | `PROCESSING` | Funding has been received and payment initiated | | `COMPLETED` | The funds are where settlement put them. A return that takes them back moves the transaction to `FAILED`, and the returned side''s `railDetails` shows `RETURNED`. A transaction stays `COMPLETED` through a return only when a later step that can''t be undone already used the funds | | `REJECTED` | Receiving institution or wallet rejected payment, payment has been refunded | | `FAILED` | The payment did not reach its destination, or the funds were sent back after it did. Not terminal for an incoming payment: a dishonored return restores the credit and moves it to `COMPLETED`. A returned payout stays `FAILED`, since it has already been refunded. Each step shows on the returned side''s `railDetails` | | `REFUNDED` | Deprecated. A refund is reported on the transaction''s `refund` object, and the status stays `FAILED` | | `EXPIRED` | Quote has expired. Terminal | ' AgentActionStatus: type: string enum: - PENDING_APPROVAL - APPROVED - REJECTED - FAILED description: 'Status of an agent action. | Status | Description | |--------|-------------| | `PENDING_APPROVAL` | Submitted by the agent, awaiting platform approval before execution | | `APPROVED` | Approved by the platform; execution is in progress or completed | | `REJECTED` | Rejected by the platform; the underlying transaction was not executed | | `FAILED` | Not executed, or execution failed; see `failureReason` | ' WireBankAccountDetails: title: Wire Bank Account Details allOf: - $ref: '#/components/schemas/UsdBankAccountDetails' - type: object properties: bankName: type: string description: Name of the account's bank. example: Chase Bank ScaChallenge: type: object description: 'A Strong Customer Authentication challenge that must be satisfied before a money-movement operation can complete. This object is **only present when the customer is in a region where SCA is required** (the EU); for customers outside SCA-regulated regions it is omitted entirely and no action is needed. When present on a quote, authorize it by submitting an `ScaAuthorization` proof to `POST /quotes/{quoteId}/authorize`. **A single operation may require more than one authorization, in sequence.** Treat `scaChallenge` as *the challenge to satisfy now*, not "the only one". After each authorize, re-inspect the returned quote/transaction: if it is still `PENDING_AUTHORIZATION`, it carries the **next** `scaChallenge` (a new `id`) — authorize that too, and repeat until it leaves `PENDING_AUTHORIZATION`. Do not assume one authorization releases the transfer. The number of authorizations is flow-dependent and **may decrease in future**: for example, a cross-currency send today authorizes the currency conversion and the payout as two separate challenges; a future update may collapse them into one. A client written to loop on status handles any count unchanged.' required: - id - expiresAt - factor - availableFactors properties: id: type: string description: Unique identifier for this challenge. The server resolves the active challenge from the quote or transaction being authorized, so this field need not be supplied back; it is informational (e.g. for logging or correlation). example: ScaChallenge:019542f5-b3e7-1d02-0000-000000000007 expiresAt: type: string format: date-time description: Absolute UTC timestamp after which this challenge can no longer be authorized. example: '2025-10-03T12:05:00Z' factor: $ref: '#/components/schemas/ScaFactor' description: The factor this challenge was issued for. Defaults to `SMS_OTP`. availableFactors: type: array description: The factors the customer may use to satisfy this challenge. items: $ref: '#/components/schemas/ScaFactor' example: - SMS_OTP purpose: type: - string - 'null' description: Optional, informational label for what this particular challenge in the sequence authorizes — useful for step UX (e.g. "Authorize the currency conversion" vs "Authorize the payout"). Known values include `CURRENCY_CONVERSION`, `PAYOUT`, and `TRANSFER`, but the set is **non-exhaustive and may grow** — treat unrecognized values as a generic authorization step and do not branch program logic on it. Omitted when steps are not distinguished (e.g. a single-authorization flow). example: PAYOUT passkeyAssertionOptions: type: - object - 'null' additionalProperties: true description: Opaque WebAuthn assertion request options (including the relying-party id, challenge, and allowed credentials), present only when `factor` is `PASSKEY`. Pass to the device's WebAuthn API to produce the assertion submitted back in `ScaAuthorization.passkeyAssertion`. passkeyAllowedOrigins: type: - array - 'null' items: type: string description: The origins the WebAuthn ceremony may run against. Populated for enrollment and login passkey challenges; the origin the assertion is produced against must be one of these and echoed back as `ScaAuthorization.origin`. Per-transaction passkey challenges omit this (they carry `passkeyAssertionOptions` only) — see `ScaAuthorization.origin` for how to source the origin in that case. example: - https://app.example.com Refund: type: object required: - reference - initiatedAt - status properties: reference: type: string description: The unique reference ID of the refund example: UMA-Q12345-REFUND initiatedAt: type: string format: date-time description: When the refund was initiated example: '2025-08-15T14:30:00Z' settledAt: type: string format: date-time description: When the refund was settled example: '2025-08-15T14:35:00Z' status: $ref: '#/components/schemas/RefundStatus' reason: $ref: '#/components/schemas/RefundReason' AccountTransactionSource: title: Account Source allOf: - $ref: '#/components/schemas/BaseTransactionSource' - type: object required: - accountId - sourceType properties: sourceType: type: string enum: - ACCOUNT accountId: type: string description: Source account identifier example: InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 railDetails: $ref: '#/components/schemas/RailDetailsOneOf' onChainTransaction: $ref: '#/components/schemas/OnChainTransaction' deprecated: true description: Deprecated. Use `railDetails`, which carries the same hash and network when `paymentRail` is `ONCHAIN`. description: Source account details AgentUpdateRequest: type: object description: Partial update to an agent's basic fields. At least one field must be provided. properties: name: type: string description: Updated name for the agent. example: Updated Payroll Agent isPaused: type: boolean description: Set to true to pause the agent or false to resume it. example: true ReconciliationInstructions: type: object minProperties: 1 description: Instructions for reconciling a payment with this transaction. For the on-chain transaction to or from an external crypto wallet that is the transaction's own source or destination, use the `railDetails` on the relevant source or destination instead. properties: reference: type: string description: Unique reference code to include with the payment to match it with the correct incoming transaction, when available. example: UMA-Q12345-REF transactionHash: deprecated: true type: string description: 'Transaction hash of the settlement transfer, when available. This field reports two different transfers, and only one of them has a replacement today: For a crypto transfer to or from a customer''s own external wallet, use the `railDetails` on the relevant source or destination instead — it names the network alongside the hash. That is the transfer this field is deprecated for. For the inter-VASP settlement leg of a UMA payment (e.g. USDC on Solana to the receiving partner), this field remains the only place the hash is reported: a UMA address is not a wallet you hold, so its source and destination carry no `railDetails`. The field will not be removed before that leg has a replacement.' example: '0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566' AgentDeviceCodeStatusResponse: type: object required: - code - status - redeemed properties: code: type: string description: The device code. example: jqzJR3AgI9OAwb_enypARw status: $ref: '#/components/schemas/AgentDeviceCodeStatus' redeemed: type: boolean description: Whether this device code was successfully redeemed. This is false for expired or invalidated codes. example: false PaymentTronWalletInfo: title: Tron Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/TronWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDT AgentQuote: title: Agent Quote allOf: - $ref: '#/components/schemas/Quote' - type: object properties: minimumReceivingAmount: type: - integer - 'null' format: int64 description: 'Smallest amount the recipient receives, in the smallest unit of `receivingCurrency`, for a quote to a `CHAIN_ADDRESS` destination: `totalReceivingAmount` is an estimate, and the quote executes only if a fresh price at execution still delivers at least this amount. Otherwise the action fails with `PRICE_MOVED`. Null for a quote whose destination is not `CHAIN_ADDRESS`.' example: 990000 destinationSparkAddress: type: string description: The Spark address this quote pays, when its `destination` is one of the customer's `SPARK_WALLET` external accounts. example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu destinationChainAddress: $ref: '#/components/schemas/AgentChainAddressDestination' description: The chain, address and stablecoin this quote pays, when it was created with a `CHAIN_ADDRESS` destination. description: 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. SwiftAccountInfo: allOf: - $ref: '#/components/schemas/SwiftAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SWIFT FedNowRailStatus: type: string enum: - PENDING - SETTLED - FAILED description: 'Status of the payment on FedNow. | Status | Description | |--------|-------------| | `PENDING` | Submitted and awaiting the receiving bank''s response. | | `SETTLED` | The receiving bank accepted the payment and the funds settled. | | `FAILED` | The receiving bank or the network rejected the payment and no funds moved. |' example: SETTLED BasePaymentAccountInfo: type: object required: - accountType properties: accountType: $ref: '#/components/schemas/PaymentAccountType' PaymentSparkWalletInfo: title: Spark Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SparkWalletInfo' - type: object required: - assetType properties: assetType: type: string description: Type of asset or configured Spark token currency code invoice: type: string description: Invoice for the payment example: sparkrt1pgss8ter0fhc4c220f3zftmpz49h8wqte8eg3m5zkrraplgc048jucgszg3ssqgjzqqekv73mmh842yj7drsjwh7t7tz5zt8wf5kghm5v4ehggszppjp5s80cg3qjdzc55g2567tn3lj705hdsr577tg8ah795mlnt6807y657qhkmgfkf9w75p4wz3l8vhua85zdn6ryj32zuj0p00pv2l5z4u47mw6h4s QuoteSourceType: type: string enum: - ACCOUNT - REALTIME_FUNDING description: Type of quote funding source example: ACCOUNT CryptoNetwork: type: string enum: - BITCOIN - ETHEREUM - SOLANA - BASE - POLYGON - TRON - PLASMA - ARBITRUM - SPARK description: The blockchain network an on-chain transaction settled on. Whether this is the mainnet or a test network (e.g. Solana devnet) is determined by your platform's environment — sandbox platforms operate on test networks, production platforms on mainnet — mirroring how `cryptoNetwork` is interpreted elsewhere in the API. example: SOLANA PaymentPolygonWalletInfo: title: Polygon Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/PolygonWalletInfo' - type: object properties: assetType: type: string description: Type of asset enum: - USDC DestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of payment destination example: ACCOUNT TransactionPendingReason: type: string enum: - COUNTERPARTY_DECLARATION_REQUIRED - WALLET_VERIFICATION_REQUIRED - COUNTERPARTY_INFORMATION_REQUIRED - COMPLIANCE_REVIEW description: 'Why a transaction is pending. | Reason | Description | |--------|-------------| | `COUNTERPARTY_DECLARATION_REQUIRED` | The customer must declare who controls the sending wallet. | | `WALLET_VERIFICATION_REQUIRED` | The customer must verify ownership of the sending wallet. | | `COUNTERPARTY_INFORMATION_REQUIRED` | Information about the sender is required. | | `COMPLIANCE_REVIEW` | The customer''s action is complete and the deposit remains under compliance review. | ' FieldError: type: object required: - field description: One field-level validation failure. Field-validation errors on submit endpoints (e.g. `POST /customers`, `PATCH /customers/{id}`) emit an array of these under `details.errors` so platforms can render form-field-level UX for every failure in a single round-trip. properties: field: type: string description: Dot-notation path to the offending field. example: identifier constraint: $ref: '#/components/schemas/FieldConstraint' message: type: string description: Human-readable explanation of what's wrong with this field. example: Value is not one of the allowed enum members. SolanaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SOLANA_WALLET address: type: string description: Solana wallet address example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg WireRailDetails: title: Wire Transfer description: A domestic wire over Fedwire. allOf: - $ref: '#/components/schemas/BaseUsdBankRailDetails' - type: object required: - paymentRail - status properties: bankAccount: $ref: '#/components/schemas/WireBankAccountDetails' paymentRail: type: string enum: - WIRE status: $ref: '#/components/schemas/WireRailStatus' imad: type: string description: Fedwire Input Message Accountability Data assigned when the wire was sent. example: 20260929MMQFMP9C000123 originatorToBeneficiaryInformation: type: string description: Free-form originator-to-beneficiary information (OBI) sent with the wire. example: INV-12345 QuoteSourceOneOf: oneOf: - $ref: '#/components/schemas/AccountQuoteSource' - $ref: '#/components/schemas/RealtimeFundingQuoteSource' discriminator: propertyName: sourceType mapping: ACCOUNT: '#/components/schemas/AccountQuoteSource' REALTIME_FUNDING: '#/components/schemas/RealtimeFundingQuoteSource' OnChainTransaction: type: object required: - transactionHash - network properties: transactionHash: type: string description: On-chain transaction hash of the crypto transfer for this leg of the transaction. example: h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx network: $ref: '#/components/schemas/CryptoNetwork' description: Blockchain network the transaction settled on (mainnet vs test network is determined by your platform environment). AgentCreateResponse: type: object description: Response returned when an agent is created, including the agent and a device code for installation. required: - agent - deviceCode properties: agent: $ref: '#/components/schemas/Agent' deviceCode: $ref: '#/components/schemas/AgentDeviceCode' TransactionDestinationType: type: string enum: - ACCOUNT - UMA_ADDRESS description: Type of transaction destination example: ACCOUNT RailDetailsOneOf: description: 'The rail transfer that moved funds for this side of the transaction. `paymentRail` determines the shape: each rail carries its own identifiers. Absent until a rail transfer exists for this side, and on sides whose funds move within Grid.' oneOf: - $ref: '#/components/schemas/OnChainRailDetails' - $ref: '#/components/schemas/AchRailDetails' - $ref: '#/components/schemas/WireRailDetails' - $ref: '#/components/schemas/FedNowRailDetails' - $ref: '#/components/schemas/RtpRailDetails' discriminator: propertyName: paymentRail mapping: ONCHAIN: '#/components/schemas/OnChainRailDetails' ACH: '#/components/schemas/AchRailDetails' ACH_SAME_DAY: '#/components/schemas/AchRailDetails' WIRE: '#/components/schemas/WireRailDetails' FEDNOW: '#/components/schemas/FedNowRailDetails' RTP: '#/components/schemas/RtpRailDetails' AgentPolicy: type: object description: Policy governing what an agent can do, how it executes actions, and its spending boundaries. required: - permissions - defaultExecutionMode - spendingLimits properties: permissions: type: array description: List of permissions granted to the agent. items: $ref: '#/components/schemas/AgentPermission' defaultExecutionMode: $ref: '#/components/schemas/AgentExecutionMode' spendingLimits: $ref: '#/components/schemas/AgentSpendingLimits' accountRestrictions: $ref: '#/components/schemas/AgentAccountRestrictions' approvalThresholds: $ref: '#/components/schemas/AgentApprovalThresholds' BaseTransactionDestination: type: object required: - destinationType properties: destinationType: $ref: '#/components/schemas/TransactionDestinationType' currency: type: string description: Currency code for the destination example: EUR AgentCreateRequest: type: object required: - name - customerId - policy properties: name: type: string description: Human-readable name to identify the agent. example: Payroll Automation Agent customerId: type: string description: The ID of the customer this agent will operate on behalf of. example: Customer:019542f5-b3e7-1d02-0000-000000000001 policy: $ref: '#/components/schemas/AgentPolicy' PaymentCopAccountInfo: title: COP Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - paymentUrl properties: accountType: type: string enum: - COP_ACCOUNT paymentUrl: type: string format: uri description: A payment URL where the customer can complete their COP deposit. example: https://payments.example.com/t/abc123 PaymentInstructions: type: object required: - accountOrWalletInfo properties: instructionsNotes: type: string description: Additional human-readable instructions for making the payment example: Please ensure the reference code is included in the payment memo/description field isPlatformAccount: type: boolean description: Indicates whether the account is a platform account or a customer account. example: true accountOrWalletInfo: description: Where to send the funds. Quotes can carry any of these types. Internal accounts return only `USD_ACCOUNT`, `EUR_ACCOUNT`, `SWIFT_ACCOUNT`, and the network wallet types; MXN, BRL, COP, ARS, Lightning, and Bitcoin L1 instructions appear only on real-time funded quotes. oneOf: - $ref: '#/components/schemas/PaymentUsdAccountInfo' - $ref: '#/components/schemas/PaymentEurAccountInfo' - $ref: '#/components/schemas/PaymentSwiftAccountInfo' - $ref: '#/components/schemas/PaymentMxnAccountInfo' - $ref: '#/components/schemas/PaymentBrlAccountInfo' - $ref: '#/components/schemas/PaymentCopAccountInfo' - $ref: '#/components/schemas/PaymentArsAccountInfo' - $ref: '#/components/schemas/PaymentSparkWalletInfo' - $ref: '#/components/schemas/PaymentLightningInvoiceInfo' - $ref: '#/components/schemas/PaymentBitcoinDepositAddressInfo' - $ref: '#/components/schemas/PaymentSolanaWalletInfo' - $ref: '#/components/schemas/PaymentEthereumWalletInfo' - $ref: '#/components/schemas/PaymentBaseWalletInfo' - $ref: '#/components/schemas/PaymentPolygonWalletInfo' - $ref: '#/components/schemas/PaymentArbitrumWalletInfo' - $ref: '#/components/schemas/PaymentTronWalletInfo' - $ref: '#/components/schemas/PaymentPlasmaWalletInfo' - $ref: '#/components/schemas/PaymentEmbeddedWalletInfo' discriminator: propertyName: accountType mapping: USD_ACCOUNT: '#/components/schemas/PaymentUsdAccountInfo' EUR_ACCOUNT: '#/components/schemas/PaymentEurAccountInfo' SWIFT_ACCOUNT: '#/components/schemas/PaymentSwiftAccountInfo' MXN_ACCOUNT: '#/components/schemas/PaymentMxnAccountInfo' BRL_ACCOUNT: '#/components/schemas/PaymentBrlAccountInfo' COP_ACCOUNT: '#/components/schemas/PaymentCopAccountInfo' ARS_ACCOUNT: '#/components/schemas/PaymentArsAccountInfo' SPARK_WALLET: '#/components/schemas/PaymentSparkWalletInfo' LIGHTNING: '#/components/schemas/PaymentLightningInvoiceInfo' BITCOIN_L1: '#/components/schemas/PaymentBitcoinDepositAddressInfo' SOLANA_WALLET: '#/components/schemas/PaymentSolanaWalletInfo' ETHEREUM_WALLET: '#/components/schemas/PaymentEthereumWalletInfo' BASE_WALLET: '#/components/schemas/PaymentBaseWalletInfo' POLYGON_WALLET: '#/components/schemas/PaymentPolygonWalletInfo' ARBITRUM_WALLET: '#/components/schemas/PaymentArbitrumWalletInfo' TRON_WALLET: '#/components/schemas/PaymentTronWalletInfo' PLASMA_WALLET: '#/components/schemas/PaymentPlasmaWalletInfo' EMBEDDED_WALLET: '#/components/schemas/PaymentEmbeddedWalletInfo' PaymentLightningInvoiceInfo: title: Lightning Invoice allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - type: object required: - invoice properties: accountType: type: string enum: - LIGHTNING invoice: type: string description: Invoice for the payment example: lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs AccountDestination: title: Account allOf: - $ref: '#/components/schemas/BaseDestination' - type: object required: - accountId - destinationType properties: destinationType: type: string enum: - ACCOUNT accountId: type: string description: Destination account identifier example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 paymentRail: allOf: - $ref: '#/components/schemas/PaymentRail' - description: The payment rail to use for the transfer. Must be one of the rails supported by the destination account. If not specified, the system will select a default rail. description: Destination account details Error400: type: object required: - reason - code properties: code: type: string description: '| Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided | | END_USER_TERMS_VERSION_NOT_FOUND | The submitted version is not supported for the agreement it was sent for | | MISSING_MANDATORY_USER_INFO | Required customer information is missing | | INVITATION_ALREADY_CLAIMED | Invitation has already been claimed | | INVITATIONS_NOT_CONFIGURED | Invitations are not configured | | INVALID_UMA_ADDRESS | UMA address format is invalid | | INVITATION_CANCELLED | Invitation has been cancelled | | INVALID_RECEIVER | Receiver is invalid | | PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response | | CERT_CHAIN_INVALID | Counterparty certificate chain is invalid | | CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired | | INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid | | MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing | | SENDER_NOT_ACCEPTED | The receiving institution declined this sender. Final; a retry returns the same answer | | AMOUNT_OUT_OF_RANGE | Amount is out of range | | INVALID_CURRENCY | Currency is invalid | | INVALID_TIMESTAMP | Timestamp is invalid | | INVALID_NONCE | Nonce is invalid | | INVALID_REQUEST_FORMAT | Request format is invalid | | INVALID_BANK_ACCOUNT | Bank account is invalid | | SELF_PAYMENT | Self payment not allowed | | PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response | | INVALID_AMOUNT | Amount is invalid | | WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set | | WEBHOOK_DELIVERY_ERROR | Webhook delivery error | | LOW_QUALITY | Document quality too low to process | | DATA_MISMATCH | Document details don''t match provided information | | EXPIRED | Document has expired | | SUSPECTED_FRAUD | Document suspected of being forged or edited | | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported | | INCOMPLETE | Document is missing pages or sides | | EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time | | SMS_OTP_CREDENTIAL_ALREADY_EXISTS | An SMS_OTP credential is already registered on the target internal account; only one SMS OTP credential is supported per internal account at this time | | PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account | | AUTH_CREDENTIAL_VERIFICATION_REQUIRED | The new email or phone number has no verified replacement credential | | AUTH_CREDENTIAL_VERIFICATION_EXPIRED | The replacement credential''s verification has expired | | STABLECOIN_PROVIDER_ACCOUNT_INVALID | The stablecoin provider account link is not usable | | STABLECOIN_PROVIDER_ACCOUNT_REVOKED | The stablecoin provider account link has been revoked | | STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED | Multiple active provider account links exist; pass `stablecoinProviderAccountId` to select one | | CARDHOLDER_KYC_NOT_APPROVED | The cardholder''s KYC status is not `APPROVED`, so a card cannot be issued | | ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED | The customer create request omits an accountholder agreement its accounts require | | TRANSACTION_SIZE_LIMIT_EXCEEDED | The requested amount exceeds the configured maximum single-transaction amount for this trade corridor or withdrawal currency | | EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED | The destination account''s ownership must be verified before this transfer can proceed | | INSUFFICIENT_FUNDS | Insufficient funds for this operation | | QUOTE_EXPIRED | The quote has expired; request a new quote | | QUOTE_RATE_UNAVAILABLE | No exchange rate is available for this corridor right now | | STABLECOIN_AMOUNT_NOT_REPRESENTABLE | The amount cannot be represented at the token''s precision | | STABLECOIN_BURN_SOURCE_NOT_SUPPORTED | The burn source account cannot be used for this operation | | STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED | Linking the external account for stablecoin operations failed | | STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED | The external account needs a link method before it can be used | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED | The external account is not linked for stablecoin operations | | STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED | This external account type is not supported for stablecoin operations | | STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED | The provider could not link the external account | | STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED | The external account must be linked with the provider first | | STABLECOIN_GRID_OPERATIONS_NOT_ENABLED | The stablecoin is not enabled for Grid operations | | STABLECOIN_NOT_PROVISIONED | The stablecoin is not provisioned for issuer operations | | STABLECOIN_OPERATION_NOT_SUPPORTED | The stablecoin does not support this operation | | STABLECOIN_PROVIDER_ERROR | The stablecoin provider rejected the operation | | STABLECOIN_PROVIDER_SOURCE_NOT_LINKED | The provider source account is not linked | | STABLECOIN_VERIFICATION_FAILED | The stablecoin could not be verified with the provider | | DOCUMENTS_REQUIRED | The destination requires supporting documents for the quote''s `purposeOfPayment` that the request did not supply. `details.missingRequirements` lists the requirement ID of each one | ' enum: - INVALID_INPUT - END_USER_TERMS_VERSION_NOT_FOUND - MISSING_MANDATORY_USER_INFO - INVITATION_ALREADY_CLAIMED - INVITATIONS_NOT_CONFIGURED - INVALID_UMA_ADDRESS - INVITATION_CANCELLED - INVALID_RECEIVER - PARSE_PAYREQ_RESPONSE_ERROR - CERT_CHAIN_INVALID - CERT_CHAIN_EXPIRED - INVALID_PUBKEY_FORMAT - MISSING_REQUIRED_UMA_PARAMETERS - SENDER_NOT_ACCEPTED - AMOUNT_OUT_OF_RANGE - INVALID_CURRENCY - INVALID_TIMESTAMP - INVALID_NONCE - INVALID_REQUEST_FORMAT - INVALID_BANK_ACCOUNT - SELF_PAYMENT - PARSE_LNURLP_RESPONSE_ERROR - INVALID_AMOUNT - WEBHOOK_ENDPOINT_NOT_SET - WEBHOOK_DELIVERY_ERROR - LOW_QUALITY - DATA_MISMATCH - EXPIRED - SUSPECTED_FRAUD - UNSUITABLE_DOCUMENT - INCOMPLETE - EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS - SMS_OTP_CREDENTIAL_ALREADY_EXISTS - PASSKEY_CREDENTIAL_ALREADY_EXISTS - AUTH_CREDENTIAL_VERIFICATION_REQUIRED - AUTH_CREDENTIAL_VERIFICATION_EXPIRED - STABLECOIN_PROVIDER_ACCOUNT_INVALID - STABLECOIN_PROVIDER_ACCOUNT_REVOKED - STABLECOIN_PROVIDER_ACCOUNT_SELECTION_REQUIRED - CARDHOLDER_KYC_NOT_APPROVED - ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED - TRANSACTION_SIZE_LIMIT_EXCEEDED - EXTERNAL_ACCOUNT_VERIFICATION_REQUIRED - INSUFFICIENT_FUNDS - QUOTE_EXPIRED - QUOTE_RATE_UNAVAILABLE - STABLECOIN_AMOUNT_NOT_REPRESENTABLE - STABLECOIN_BURN_SOURCE_NOT_SUPPORTED - STABLECOIN_EXTERNAL_ACCOUNT_LINK_FAILED - STABLECOIN_EXTERNAL_ACCOUNT_LINK_METHOD_REQUIRED - STABLECOIN_EXTERNAL_ACCOUNT_NOT_LINKED - STABLECOIN_EXTERNAL_ACCOUNT_NOT_SUPPORTED - STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_FAILED - STABLECOIN_EXTERNAL_ACCOUNT_PROVIDER_LINK_REQUIRED - STABLECOIN_GRID_OPERATIONS_NOT_ENABLED - STABLECOIN_NOT_PROVISIONED - STABLECOIN_OPERATION_NOT_SUPPORTED - STABLECOIN_PROVIDER_ERROR - STABLECOIN_PROVIDER_SOURCE_NOT_LINKED - STABLECOIN_VERIFICATION_FAILED - DOCUMENTS_REQUIRED reason: type: string description: Error message details: type: object description: Additional error details. Shape varies by `code`. For field-validation errors on submit endpoints (e.g. `POST /customers`, `PATCH /customers/{id}`), `details.errors[]` enumerates every invalid field so platforms can render form-field-level UX for the entire request in a single round-trip. properties: errors: type: array description: One entry per invalid field. Present on field-validation errors from submit endpoints. items: $ref: '#/components/schemas/FieldError' missingRequirements: type: array description: The requirement ID of each required document that the quote request did not supply. Present on `DOCUMENTS_REQUIRED`. items: $ref: '#/components/schemas/PaymentDocumentRequirementId' additionalProperties: true CounterpartyInformation: type: object description: Additional information about the counterparty, if available and relevant to the transaction and platform. additionalProperties: true example: FULL_NAME: John Sender BIRTH_DATE: '1985-06-15' NATIONALITY: DE securitySchemes: BasicAuth: type: http scheme: basic description: API token authentication using format `:` AgentAuth: type: http scheme: bearer description: '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.' WebhookSignature: type: apiKey in: header name: X-Grid-Signature description: 'Secp256r1 (P-256) asymmetric signature of the webhook payload, which can be used to verify that the webhook was sent by Grid. To verify the signature: 1. Get the Grid public key provided to you during integration 2. Decode the base64 signature from the header 3. Create a SHA-256 hash of the request body 4. Verify the signature using the public key and the hash If the signature verification succeeds, the webhook is authentic. If not, it should be rejected. ' x-provenance: method: harvested publisher: Lightspark source: https://docs.lightspark.com/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)