> ## Documentation Index > Fetch the complete documentation index at: https://agents-docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an internal account > Create a rule-based internal account. A rule-based account is an additional account number for an account holder that already holds an account in the same currency. It carries a routing rule: every payment that settles into it is attributed to that account number and then swept to the rule's destination, so you can issue one number per payer and reconcile incoming payments without matching on remittance text. Only `RULE_BASED` accounts can be created here. `INTERNAL_FIAT`, `INTERNAL_CRYPTO`, and `EMBEDDED_WALLET` accounts are provisioned automatically when an account holder is created or approved. The response carries the account's own `fundingPaymentInstructions` — the routable number payers send to for a `USD` account, or one deposit address per supported network for a `USDC` or `USDT` account. Rule-based accounts are currently available in `USD`, `USDC`, and `USDT`, for a customer or for your platform itself. `USDC` and `USDT` rule-based accounts are enabled per platform. For customers in a region where Strong Customer Authentication is required (the EU), the create request returns `202` with the account in `PENDING_AUTHORIZATION` and an `scaChallenge`: the account holder authorizes the account's sweep instruction once with `POST /internal-accounts/{id}/authorize`, after which the account is `ACTIVE` and later sweeps need no further authorization. An external destination must already be a trusted beneficiary (`POST /customers/external-accounts/{externalAccountId}/trust`). Retrying the create request with the same `Idempotency-Key` while the account is still `PENDING_AUTHORIZATION` returns it with a live challenge, issuing a new one if the previous challenge expired. Sandbox platforms can create rule-based accounts and exercise the whole flow. The account number is generated locally rather than issued by a partner bank, and `POST /sandbox/internal-accounts/{accountId}/fund` stands in for a settled deposit — funding the account triggers its sweep just as a real deposit would. Send an `Idempotency-Key` header to make retries safe: a request carrying a key already used returns the account created by the first request with a `200` instead of a `201`. Reusing a key for a materially different account is rejected with `409`. Without a key a retry cannot be recognised, so each request creates its own account and mints its own account number. ## OpenAPI ````yaml /openapi.yaml post /internal-accounts openapi: 3.1.0 info: title: Grid 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: Platform Configuration description: >- Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: >- Customer management endpoints for creating and updating customer information - name: Contact Verification description: >- Endpoints for verifying a customer's email and phone via one-time codes. Required only for customers whose payment provider mandates contact verification (e.g. EU customers); other providers return 409. - name: Strong Customer Authentication description: >- Endpoints for authorizing money-movement operations that require Strong Customer Authentication. Relevant only for customers in a region where SCA is required (e.g. EU); customers outside SCA-regulated regions never see an SCA challenge and these endpoints return 409. - name: KYC/KYB Verifications description: >- Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents description: >- Endpoints for uploading and managing verification documents for customers and beneficial owners. Supports KYC and KYB document requirements. - name: Internal Accounts description: >- Internal account management endpoints for creating and managing internal accounts - name: Periodic Statements description: > Build, deliver, and evidence a Regulation E periodic statement for a customer's internal account. A statement period is a calendar month in US Central time (`America/Chicago`). A statement is issued for each customer's own USD internal account and covers their whole balance. Money received through a rule-based account appears on its owner's statement; rule-based, bulk settlement and platform-owned accounts have no statement of their own. **1. The statement — `GET /internal-accounts/{id}/balance-changes?startDate=&endDate=`** One row per change to the balance, in the order the money moved, with the opening and closing balances for the window in the same response. Page until `hasMore` is false, then assert this identity across every page before you render anything: ``` openingBalance + Σ(data[].amount) == closingBalance ``` If it does not hold, do not send the statement; contact support instead. `startDate` and `endDate` bound a half-open window `[startDate, endDate)`: for a monthly statement, pass the first instant of the month and the first instant of the following month, both in US Central time (for August 2026, `2026-08-01T00:00:00-05:00` and `2026-09-01T00:00:00-05:00`). Grid records a statement as fetched only for a window that is exactly one such month. **2. The receipt — `POST /internal-accounts/{id}/confirm-statement`** Once a month, after you have pulled and issued a period's statement, send a receipt with the `statementMonth` it covers. Grid stores it as the delivery record for that account and period. Sending it again is harmless: the first receipt's time is kept. **Timing** A window whose card settlement has not closed is refused with `409 NOT_YET_AVAILABLE` rather than answered with figures that could still change; retry once it has settled. - name: External Accounts description: >- External account management endpoints for creating and managing external bank accounts - name: Same-Currency Transfers description: >- Deprecated endpoints for transferring funds between internal and external accounts with the same currency. Use the quote endpoints under Cross-Currency Transfers instead, which now serve same-currency transfers as well. - name: Cross-Currency Transfers description: >- Endpoints for creating and confirming quotes for transfers, both same-currency and cross-currency - name: Payout Runs description: >- Endpoints for paying many recipients from one internal account in one request, and for reconciling the result - name: Settlement Rules description: >- Endpoints for standing instructions that split a customer's matching incoming payments among recipients as soon as the payments complete - name: Transactions description: Endpoints for retrieving transaction information - name: Webhooks description: Webhook endpoints and configuration for receiving notifications - name: Invitations description: Endpoints for creating, claiming and managing UMA invitations - name: Sandbox description: Endpoints to trigger test cases in sandbox - name: API Tokens description: Endpoints to programmatically manage API tokens - name: Exchange Rates description: >- Endpoints for retrieving cached foreign exchange rates. Rates are cached for approximately 5 minutes and include platform-specific fees. - name: Discoveries description: >- Endpoints for discovering available payment rails, banks, and providers for a given country and currency corridor. - name: Embedded Wallet Auth description: >- Endpoints for registering and verifying end-user authentication credentials (email OTP, OAuth, passkey) used to sign Embedded Wallet actions. - name: Agent Management description: >- Endpoints for creating and managing agents, 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. - name: Agent Operations description: >- Endpoints called by the agent itself using its own credentials (obtained via device code redemption). Scoped to the agent's associated customer — all requests automatically operate on behalf of that customer and are subject to the agent's policy. When a request requires approval, it is held as an agent action in `PENDING_APPROVAL` until the platform approves it via `POST /agents/{agentId}/actions/{actionId}/approve` or rejects it. - name: Claimable Payouts description: >- Endpoints the platform's claim page calls for a claimable payout an agent sent to a person by phone number or email: issue the claim token for the recipient's link, look the payout up by it, list how Grid can pay her, lock a quote to her account and confirm it. - name: Cards description: >- Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage a card's funding source, and list card transactions. - name: Stablecoins description: >- Stablecoin issuance endpoints. Link provider accounts, register provider-created stablecoins, create direct mint/burn issuer operations, and track operation status. - name: Embedded Care description: | A support chat between the cardholder and Lightspark's care agent, driven from the partner's own app. The platform calls with its ordinary Grid credential, but the person typing is the cardholder rather than the caller, so reaching that cardholder's account takes a second proof: an SMS code they send into the chat, after which the partner carries a session token in the `X-Ls-Care-Session` header. **The surface is two routes, and verification happens inside the conversation.** 1. **Open the chat.** `POST /care/chats/{chatId}/messages` with an empty `message`, addressed to the cardholder as `Customer:`. Returns the chat's id and the agent's opening line in `reply`, which is what a chat window renders before anybody has typed. Sends no SMS, needs no `Idempotency-Key` and consumes none, and is safe to call again: a widget that reloaded gets the same chat back, this time without a `reply`. 2. **Send the cardholder's first message.** The same route with their text and an `Idempotency-Key` header. One turn runs synchronously and the agent's answer comes back in `reply`. On a chat that cannot yet reach the account this call also texts the cardholder a code, and the agent's `reply` asks for it. 3. **The cardholder sends the code as an ordinary message.** When it is correct, the response to that turn carries `sessionToken` and `expiresAt`. Send that token as the `X-Ls-Care-Session` header on every message from then on. A code that does not match is answered in `reply`, and the cardholder can simply send it again. 4. **Close the chat** with `DELETE /care/chats/{chatId}` when the cardholder is done. Every response also carries `chatEnded`, and the agent can end the chat itself: when `chatEnded` is true, the closing line is in `reply` and the chat takes no further messages, so stop sending to it. An opening addressed to that `CareChat:` answers `409 CARE_CHAT_ENDED`; address the cardholder as `Customer:` to open a new chat. **Render `redactedCustomerMessage` if present, then `reply` if present.** That one rule covers an opening, a resume and a turn. **A cardholder whose code never arrived asks the agent for another one.** The agent sends a new code to the number on file and says so in its `reply`. There is no separate route for it. **The verification fields are optional hints.** `verificationRequired` and `codeLength` let an app show a dedicated one-time-code input of the right length, marked as a one-time code so iOS and Android offer to fill it from the SMS. A partner can ignore them, since the agent asks for the code in its reply and says where it went, and the app still sends the code as an ordinary message. Step 1 is optional. A message addressed to a `Customer:` id opens that cardholder's chat if they have none, so a partner whose cardholder has just typed something spends one call rather than two. A cardholder who has not verified yet is never a `401`, because the first message from every new cardholder is unverified and a `401` there would be indistinguishable from a bad credential. On these endpoints a `401` means the platform's Grid credential is wrong, the session token presented is malformed, or a replay lacks the session token its original request required. **Verification expires, and a lost session is recoverable in the chat.** A chat reaches the cardholder's account only while its verification is newer than the session lifetime, fifteen minutes in the default deployment, which is also how long a session token lives. Past that window a message gets a fresh code, and the agent asks the cardholder to send it back inside the conversation, which hands the partner the next session token. A new message sent with no `X-Ls-Care-Session` header, or with a token past its expiry, on a chat whose verification is still current is treated the same way: the verification is cancelled before the turn runs, a new code is sent, and the agent asks for it. So a client that lost its token, or held one too long, simply keeps sending messages. Only a token that is malformed, or that was minted for another platform, chat or cardholder, is refused. Two things an integration has to get right: - **Render `redactedCustomerMessage`, never your own copy of what was typed.** Grid masks card numbers and other sensitive digit strings in it. A UI that renders its own copy of the input instead puts a card number the cardholder pasted back on their screen unmasked, and into your logs. - **The session token is returned once and is never re-readable.** No endpoint hands it back, it cannot be revoked, and it is short-lived by design. Hold it for the life of the cardholder's session. It arrives on the message response to the turn in which the cardholder sent their code, and on no other. Losing it costs the cardholder a new code, never access to the chat. Some things are absent by construction, so no integration can come to depend on them: nothing returns a transcript or an earlier turn's reply (retrying under the original `Idempotency-Key` is how an answer that was produced but not delivered is recovered; a replay requires the same session token its original request required and never carries a `sessionToken`, so a lost token is recovered by sending the cardholder's next message as a new message, which verifies them again), nothing sets a verification state, and nothing changes the number a code is sent to. Errors from these endpoints carry `code` and `reason` only (see the `CareError` schema), unlike the `Error4xx` schemas used elsewhere in this specification. paths: /internal-accounts: post: tags: - Internal Accounts summary: Create an internal account description: > Create a rule-based internal account. A rule-based account is an additional account number for an account holder that already holds an account in the same currency. It carries a routing rule: every payment that settles into it is attributed to that account number and then swept to the rule's destination, so you can issue one number per payer and reconcile incoming payments without matching on remittance text. Only `RULE_BASED` accounts can be created here. `INTERNAL_FIAT`, `INTERNAL_CRYPTO`, and `EMBEDDED_WALLET` accounts are provisioned automatically when an account holder is created or approved. The response carries the account's own `fundingPaymentInstructions` — the routable number payers send to for a `USD` account, or one deposit address per supported network for a `USDC` or `USDT` account. Rule-based accounts are currently available in `USD`, `USDC`, and `USDT`, for a customer or for your platform itself. `USDC` and `USDT` rule-based accounts are enabled per platform. For customers in a region where Strong Customer Authentication is required (the EU), the create request returns `202` with the account in `PENDING_AUTHORIZATION` and an `scaChallenge`: the account holder authorizes the account's sweep instruction once with `POST /internal-accounts/{id}/authorize`, after which the account is `ACTIVE` and later sweeps need no further authorization. An external destination must already be a trusted beneficiary (`POST /customers/external-accounts/{externalAccountId}/trust`). Retrying the create request with the same `Idempotency-Key` while the account is still `PENDING_AUTHORIZATION` returns it with a live challenge, issuing a new one if the previous challenge expired. Sandbox platforms can create rule-based accounts and exercise the whole flow. The account number is generated locally rather than issued by a partner bank, and `POST /sandbox/internal-accounts/{accountId}/fund` stands in for a settled deposit — funding the account triggers its sweep just as a real deposit would. Send an `Idempotency-Key` header to make retries safe: a request carrying a key already used returns the account created by the first request with a `200` instead of a `201`. Reusing a key for a materially different account is rejected with `409`. Without a key a retry cannot be recognised, so each request creates its own account and mints its own account number. operationId: createInternalAccount parameters: - name: Idempotency-Key in: header description: > A unique identifier for the request. Strongly recommended: creating the account mints an account number that cannot be reversed, and the key is what lets a retry return the first account rather than minting a second. required: false schema: type: string maxLength: 255 example: 550e8400-e29b-41d4-a716-446655440000 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InternalAccountCreateRequest' examples: externalDestination: summary: Forward every payment to an external account over ACH value: customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: RULE_BASED currency: USD label: invoice-4417 sweepRule: destination: accountId: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 paymentRail: ACH purposeOfPayment: SELF description: Rent sweep remittanceInformation: Unit 4B March internalDestination: summary: Forward every payment to another internal account value: customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: RULE_BASED currency: USD label: payer-northwind sweepRule: destination: accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 usdcDepositAddress: summary: Issue USDC deposit addresses that sweep into a USD account value: customerId: Customer:019542f5-b3e7-1d02-0000-000000000001 type: RULE_BASED currency: USDC label: payer-northwind sweepRule: destination: accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 onBehalfOfCustomer: summary: A platform account that receives payments for a customer value: onBehalfOfCustomerId: Customer:019542f5-b3e7-1d02-0000-000000000002 type: RULE_BASED currency: USD label: customer-0002-collections sweepRule: destination: accountId: InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 responses: '200': description: >- The `Idempotency-Key` was already used to create this account. The account created by the first request is returned unchanged. content: application/json: schema: $ref: '#/components/schemas/InternalAccount' '201': description: >- Internal account created. `fundingPaymentInstructions` carries the account's own number. content: application/json: schema: $ref: '#/components/schemas/InternalAccount' '202': description: >- Internal account created, but waiting for Strong Customer Authentication. Returned only for customers in a region where SCA is required (the EU): the account is `PENDING_AUTHORIZATION` and carries the `scaChallenge` that opens it. Authorize it with `POST /internal-accounts/{id}/authorize`. content: application/json: schema: $ref: '#/components/schemas/InternalAccount' '400': description: >- Bad request. Returned when `type` is not `RULE_BASED`, when `sweepRule` is missing, when the currency is not supported for rule-based accounts, when the account holder has no account in that currency yet, when the destination cannot accept the requested payment rail, and for general invalid parameters. content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden - rule-based accounts are not enabled for this platform. content: application/json: schema: $ref: '#/components/schemas/Error403' '404': description: Customer or destination account not found content: application/json: schema: $ref: '#/components/schemas/Error404' '409': description: >- Conflict - the `Idempotency-Key` was already used to create a materially different account (use a new key for a new account). Also returned with `BENEFICIARY_NOT_TRUSTED` when the sweep destination must be a trusted beneficiary and is not, and with `SCA_SESSION_REQUIRED` when the customer's SCA login session is missing or expired. content: application/json: schema: $ref: '#/components/schemas/Error409' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - BasicAuth: [] components: schemas: InternalAccountCreateRequest: title: Internal Account Create Request type: object description: >- Request body for `POST /internal-accounts`. Only `RULE_BASED` accounts can be created today, and they are rejected without a `sweepRule` — the type and its rule are created together or not at all. required: - type - currency properties: customerId: type: string description: >- The customer the account is created for. Omit it to create a platform-owned account. The account holder must already have a verified account in the same currency, which is where funds land when a sweep cannot be completed. example: Customer:019542f5-b3e7-1d02-0000-000000000001 type: allOf: - $ref: '#/components/schemas/InternalAccountType' description: >- Must be `RULE_BASED`. `INTERNAL_FIAT`, `INTERNAL_CRYPTO`, `BULK_SETTLEMENT`, and `EMBEDDED_WALLET` accounts are provisioned when a customer is created or approved. example: RULE_BASED currency: type: string description: >- Currency code the account is denominated in. Rule-based accounts are currently available in `USD`, `USDC`, and `USDT`. A `USD` account is issued its own bank account number; a `USDC` or `USDT` account is issued its own deposit address on each network your platform supports. For customers in a region where Strong Customer Authentication is required (the EU), rule-based accounts are available in `EUR`, `USDC`, and `BTC`, and every sweep converts currency: an `EUR` account sweeps to a crypto destination, and a `USDC` or `BTC` account sweeps to an `EUR` destination. See the rule-based accounts guide for the supported combinations. example: USD onBehalfOfCustomerId: type: string description: >- For regulated financial institutions only. The customer whose payments this platform-owned account receives. Only accepted when `customerId` is omitted, so the account stays yours; it records who incoming payments are for. The customer must belong to your platform. Several of your accounts can name the same customer. example: Customer:019542f5-b3e7-1d02-0000-000000000002 label: type: string maxLength: 255 description: >- Your own name for the account, echoed back on reads. Useful for identifying which payer the account was issued for. example: invoice-4417 sweepRule: allOf: - $ref: '#/components/schemas/SweepRuleRequest' description: >- The routing rule for the account. Required when `type` is `RULE_BASED`, which is the only type this endpoint creates today: a rule-based account with no rule has no meaning, so the two are written together. scaFactor: $ref: '#/components/schemas/ScaFactor' description: >- Optional preferred factor for the Strong Customer Authentication challenge that authorizes the account's standing instruction. Only relevant for customers in a region where SCA is required (e.g. EU); ignored otherwise. `SMS_OTP` (default), `TOTP`, and `PASSKEY` are all accepted, because the challenge authorizes the instruction rather than a single amount and payee. InternalAccount: type: object required: - id - type - status - balance - totalBalance - fundingPaymentInstructions - createdAt - updatedAt properties: id: type: string description: The ID of the internal account example: InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123 customerId: type: string description: >- The ID of the customer associated with the internal account. If this field is empty, the internal account belongs to the platform. example: Customer:019542f5-b3e7-1d02-0000-000000000001 type: $ref: '#/components/schemas/InternalAccountType' status: $ref: '#/components/schemas/InternalAccountStatus' balance: $ref: '#/components/schemas/CurrencyAmount' description: The balance available to spend, excluding pending and held funds totalBalance: $ref: '#/components/schemas/CurrencyAmount' description: The total balance, including pending and held funds fundingPaymentInstructions: type: array description: >- Payment instructions for funding the account. Empty while funding is withheld. Only bank (`USD_ACCOUNT`, `EUR_ACCOUNT`, `SWIFT_ACCOUNT`) and network wallet types appear here. items: $ref: '#/components/schemas/PaymentInstructions' onBehalfOfCustomerId: type: string description: >- The customer whose payments this platform-owned account receives. Only set by regulated financial institutions. Omitted for accounts that name no such customer, which includes every account owned by a customer. example: Customer:019542f5-b3e7-1d02-0000-000000000002 label: type: string maxLength: 255 description: >- The platform-supplied label recorded when the account was created. Null for accounts that carry none. example: invoice-4417 sweepRule: allOf: - $ref: '#/components/schemas/SweepRule' description: >- The routing rule attached to this account. Null for accounts that carry no rule, which is every account other than a `RULE_BASED` one. scaChallenge: allOf: - $ref: '#/components/schemas/ScaChallenge' description: >- The Strong Customer Authentication challenge the account holder must satisfy before a `RULE_BASED` account opens. Present only while the account is `PENDING_AUTHORIZATION`, and only for customers in a region where SCA is required (the EU). Authorize it with `POST /internal-accounts/{id}/authorize`. If the challenge expires, retry the create request with the same `Idempotency-Key` to receive a new one. strandedBalances: type: array description: >- Funds a `RULE_BASED` account's sweep converted but could not deliver to the rule's destination, by currency. They are held for the account holder and can be moved to their own account in that currency with `POST /internal-accounts/{id}/stranded-funds/transfer`. Omitted when there are none, and for every account other than a `RULE_BASED` one. items: $ref: '#/components/schemas/CurrencyAmount' privateEnabled: type: boolean description: >- Whether wallet privacy is enabled for the Embedded Wallet. Only present for `EMBEDDED_WALLET` internal accounts. example: true cardCapabilities: $ref: '#/components/schemas/CardCapabilities' description: >- Actions supported for a card issued now with this account as its funding source. They can change if the platform's card routing changes and do not describe cards already issued using the account. The funding source a create request supplies selects the issuer and therefore the resulting card's capabilities; read this field from that account. Absent when this account cannot fund a card. createdAt: type: string format: date-time description: Timestamp when the internal account was created example: '2025-10-03T12:30:00Z' updatedAt: type: string format: date-time description: Timestamp when the internal account was last updated example: '2025-10-03T12:30:00Z' Error400: type: object required: - reason - code properties: code: type: string description: > | Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided. When Grid knows the cause, `details.refusalReason` names it. When a card cannot be issued because the customer record lacks fields, it is `CARDHOLDER_INFO_MISSING` and `details.missingFields` lists them | | 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 | The account holder already has an EMAIL_OTP credential on the target internal account; the holder may have one. Administrators' credentials, added with `POST /auth/admin-credentials`, are not counted | | 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 | | STORED_CARD_VERIFICATION_FAILED | The card's issuer did not confirm the card: its security code, billing address or name did not match. Nothing was stored | | 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 | | CARDHOLDER_AGREEMENT_NOT_ACCEPTED | The customer has not accepted the cardholder agreement the platform requires before a card is issued | | 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 | | EXACT_AMOUNT_UNAVAILABLE | The quote cannot deliver exactly the requested receiving amount at the current rate; quote again shortly or lock the sending amount | 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 - STORED_CARD_VERIFICATION_FAILED - CARDHOLDER_KYC_NOT_APPROVED - ACCOUNTHOLDER_AGREEMENT_NOT_ACCEPTED - CARDHOLDER_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 - EXACT_AMOUNT_UNAVAILABLE 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' refusalReason: $ref: '#/components/schemas/RefusalReason' missingFields: type: array description: >- Each customer field the request needs but the customer record lacks, named as in `CustomerInfoFieldName` (for example `PHONE_NUMBER`). Present with refusal reason `CARDHOLDER_INFO_MISSING`. Grid may name fields not yet listed there. items: type: string example: PHONE_NUMBER additionalProperties: true 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 Error403: type: object required: - reason - code properties: code: type: string description: > | Error Code | Description | |------------|-------------| | FORBIDDEN | Insufficient permissions. `details.refusalReason` names the cause when Grid knows it | | 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 | | CORRIDOR_UNDER_MAINTENANCE | Payments to this corridor are paused for maintenance. | enum: - FORBIDDEN - USER_NOT_READY - COUNTERPARTY_NOT_ALLOWED - VELOCITY_LIMIT_EXCEEDED - END_USER_TERMS_NOT_ACCEPTED - CUSTOMER_NOT_VERIFIED - SANCTION_BLOCKED - DESTINATION_NOT_ALLOWED - CORRIDOR_UNDER_MAINTENANCE reason: type: string description: Error message details: type: object description: >- Additional error details. Shape varies by `code`. A `FORBIDDEN` refusal with a known cause carries `refusalReason`, plus the fields that reason names. properties: refusalReason: $ref: '#/components/schemas/RefusalReason' permission: type: string description: >- The `AgentPermission` the agent's policy lacks. Present with refusal reason `AGENT_PERMISSION_REQUIRED`. Grid may add permissions, so accept a value not yet listed there. example: ISSUE_CARDS policyDenialReason: $ref: '#/components/schemas/AgentPolicyDenialReason' description: >- The policy rule that denied the quote or purchase card. Present with refusal reason `AGENT_POLICY_DENIED` or `AGENT_PURCHASE_CARD_POLICY_DENIED`. additionalProperties: true 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 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 | | PASSKEY_ALREADY_ENROLLED | The customer already has the most passkeys allowed (two). Delete 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_NOT_TRUSTED | The external account must be a trusted beneficiary before it can be used here. Trust it first via `POST /customers/external-accounts/{externalAccountId}/trust` (and its `/confirm`), then retry | | 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 | | AGENT_CARD_EXISTS | The agent already holds a card that is not `CLOSED`, so it cannot issue another. Close that card first | | PURCHASE_CARD_LIMIT_REACHED | The agent already holds the most open purchase cards allowed, counting purchase cards awaiting approval. Use or close one first | | 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. When the cardholder already holds the one card the platform allows, `details.refusalReason` is `CARDHOLDER_HOLDS_CARD` | | DOCUMENT_ALREADY_EXISTS | A document of this type already exists for the holder; replace it with PUT | | DUPLICATE_EXTERNAL_ACCOUNT | The `platformAccountId` is already used, or, without one, the wallet is already registered. 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_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 | | INVOICE_ALREADY_USED | Another quote for the Lightning invoice can still be executed or funded, or was executed. An invoice has one live quote at a time; ask the recipient for a new one, or retry once Grid has closed the earlier quote as expired | enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL - TRANSACTION_NOT_CANCELLABLE - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED - BENEFICIARY_NOT_TRUSTED - BENEFICIARY_TRUSTED - BANK_ACCOUNT_VALIDATION_PENDING - INVALID_STATE_TRANSITION - CARD_ALREADY_CLOSED - CARD_NOT_MUTABLE - PIN_CHANGE_REQUIRED - AGENT_CARD_EXISTS - PURCHASE_CARD_LIMIT_REACHED - 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_PHONE_NUMBER_ALREADY_EXISTS - STABLECOIN_SYMBOL_ALREADY_EXISTS - STABLECOIN_TOKEN_IDENTIFIER_ALREADY_EXISTS - WALLET_NOT_PROVISIONED - PAYMENT_DOCUMENT_ALREADY_USED - INVOICE_ALREADY_USED reason: type: string description: Error message details: type: object description: Additional error details additionalProperties: true 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 InternalAccountType: title: Internal Account Type type: string enum: - INTERNAL_FIAT - INTERNAL_CRYPTO - EMBEDDED_WALLET - RULE_BASED - BULK_SETTLEMENT description: >- Classification of an internal account. - `INTERNAL_FIAT`: A Grid-managed fiat holding account (for example, the USD holding account used as the source for Payouts flows). - `INTERNAL_CRYPTO`: A Grid-managed crypto holding account denominated in a stablecoin such as USDC. - `EMBEDDED_WALLET`: A self-custodial Embedded Wallet provisioned for the customer. Outbound transfers require a session signature produced by the customer's device — see the Embedded Wallets guide. - `RULE_BASED`: An additional account number for an existing account holder, with a routing rule attached, so incoming payments can be attributed to a specific payer and swept automatically. Created with `POST /internal-accounts`. - `BULK_SETTLEMENT`: An account for receiving bulk payments (for example, a single settlement from a payment processor) that the platform then pays out to its customers. Only a platform can hold one, and funds in it can move only to the platform's customers. SweepRuleRequest: title: Sweep Rule Request type: object description: >- The routing rule attached to a rule-based account. Every payment that settles into the account is swept to the rule's destination, carrying the payment metadata configured here. required: - destination properties: destination: allOf: - $ref: '#/components/schemas/SweepRuleDestinationRequest' description: Where funds that settle into this account are swept. purposeOfPayment: allOf: - $ref: '#/components/schemas/PurposeOfPayment' description: >- The purpose of payment applied to each sweep. Required by some destination geographies. example: SELF description: type: string maxLength: 255 description: >- Free-form description recorded on each sweep. Not delivered to the recipient; use `remittanceInformation` for that. example: Rent sweep remittanceInformation: type: string maxLength: 1024 description: >- Free-form information that travels with each sweep to the recipient. The field this populates depends on the payment rail: for ACH it populates the Addenda record, for FedNow and RTP it populates the remittanceInformation field, and for wires it populates the OBI (Originator to Beneficiary Information) / beneficiary information. Only printable ASCII characters are accepted, because the underlying rails carry nothing else. example: Unit 4B March platformFeeOverride: allOf: - $ref: '#/components/schemas/PlatformFeeOverride' description: >- Fee terms applied to every sweep this rule drives. Omit it to use the platform's configured fees. 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. | InternalAccountStatus: title: Internal Account Status type: string enum: - PENDING - PENDING_AUTHORIZATION - ACTIVE - CLOSED - FROZEN - FAILED description: >- Status of a Grid internal account. The status determines whether the account can send or receive payments. - `PENDING`: The account is under review and is being provisioned. The account cannot send or receive payments until provisioning completes. - `PENDING_AUTHORIZATION`: The account is provisioned but waiting for the account holder to satisfy its Strong Customer Authentication challenge (`scaChallenge`). Only `RULE_BASED` accounts for customers in a region where SCA is required (the EU) enter this status. The account cannot receive payments until it is authorized with `POST /internal-accounts/{id}/authorize`. - `ACTIVE`: The account is ready to send and receive payments. - `CLOSED`: The account cannot send or receive payments. A customer can initiate the closing of an internal account, after which the account transitions to this status. - `FROZEN`: The account cannot send or receive payments. Grid may freeze an account in response to compliance or fraud signals; payments are blocked while the account remains frozen. - `FAILED`: The account could not be provisioned. Grid was unable to create the underlying account, so it cannot send or receive payments and requires remediation. example: ACTIVE 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' 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' SweepRule: title: Sweep Rule type: object description: >- The routing rule attached to a rule-based account. Returned on the account rather than as a resource of its own, because the rule has no lifecycle apart from the account. required: - destination properties: destination: allOf: - $ref: '#/components/schemas/SweepRuleDestination' description: Where funds that settle into this account are swept. minimumAmount: allOf: - $ref: '#/components/schemas/CurrencyAmount' description: >- **In this rule-based account's currency, not the destination's.** The smallest balance the corridor to the destination can carry; a settled balance below it is not swept. Zero means no floor, which is the case for a same-currency internal destination — a book transfer with no rail, fee or conversion to justify one. Configuration rather than a moving estimate, so there is nothing to re-poll. maximumAmount: allOf: - $ref: '#/components/schemas/CurrencyAmount' description: >- **In this rule-based account's currency, not the destination's.** The largest balance the corridor to the destination can carry; a settled balance above it is not swept. Null means no ceiling. purposeOfPayment: allOf: - $ref: '#/components/schemas/PurposeOfPayment' description: The purpose of payment applied to each sweep. example: SELF description: type: string description: >- Free-form description recorded on each sweep. Not delivered to the recipient. example: Rent sweep remittanceInformation: type: string description: Free-form information that travels with each sweep to the recipient. example: Unit 4B March platformFeeOverride: allOf: - $ref: '#/components/schemas/PlatformFeeOverride' description: >- Fee terms applied to every sweep this rule drives. Null when the platform's configured fees apply. 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`, `TRANSFER`, and `STANDING_INSTRUCTION` (authorizing a rule-based account's sweep instruction), 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 CardCapabilities: type: object description: Actions supported by the card program associated with this resource. required: - supportsVelocityLimits - supports3dSecurePassword - supportsPanReveal - supportsDigitalWalletTokenization properties: supportsVelocityLimits: type: boolean description: >- Whether this card program supports platform-managed limits through `/card-velocity-limits`. Supported where Grid makes authorization decisions; false where the issuer makes them. Amounts use the card's currency, regardless of its funding source. example: true supports3dSecurePassword: type: boolean description: >- Whether cards in this program accept a caller-supplied `threeDSecurePassword`. example: false supportsPanReveal: type: boolean description: >- Whether cards in this program can be revealed through `POST /cards/{id}/reveal`. example: true supportsDigitalWalletTokenization: type: boolean description: >- Whether cards in this program can be added to Apple Pay, Google Pay, or Samsung Pay from your app through `POST /cards/{id}/tokenize`. Manual entry into a wallet works regardless of this flag. example: true 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. 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 RefusalReason: type: string description: > Why Grid refused the request, as `details.refusalReason`. Several refusals share one `code`, and `reason` is a message that may be reworded, so branch on this value rather than on `reason`. Treat it as an open set, not a fixed list: Grid may add values, and an unknown one is a refusal without a known cause. | Refusal reason | Status | Description | |----------------|--------|-------------| | `AGENT_API_DISABLED` | 403 | The agent API is not enabled for the platform | | `AGENT_CUSTOMER_INACTIVE` | 403 | The agent's customer is not active | | `AGENT_INACTIVE` | 403 | The agent is paused or deleted | | `AGENT_NO_DELEGATED_KEY` | 403 | The agent holds no active delegated key for the source wallet | | `AGENT_PERMISSION_REQUIRED` | 403 | The agent's policy lacks a permission this call needs. `details.permission` names it | | `AGENT_ACCOUNT_NOT_ALLOWED` | 403 | The agent's policy does not allow the source account or funding source | | `AGENT_DEPOSIT_ACCOUNT_NOT_ALLOWED` | 403 | The agent's policy does not allow deposits to this account | | `AGENT_POLICY_DENIED` | 403 | The agent's policy denied executing the quote. `details.policyDenialReason` says which rule | | `AGENT_QUOTE_HELD` | 403 | The quote cannot be sent and is held for manual follow-up | | `AGENT_CARDS_DISABLED` | 403 | Agent cards are not enabled for the platform | | `AGENT_CARDS_CUSTOMER_NOT_VERIFIED` | 403 | Agent cards need a verified individual customer | | `AGENT_CARD_HANDOVER_DISABLED` | 403 | Handing an agent's card over to its customer is not enabled for the platform | | `AGENT_PURCHASE_CARDS_DISABLED` | 403 | Agent purchase cards are not enabled for the platform | | `AGENT_RECURRING_PURCHASE_CARDS_DISABLED` | 403 | Agent recurring purchase cards are not enabled for the platform | | `AGENT_PURCHASE_CARD_POLICY_DENIED` | 403 | The agent's policy denied the purchase card. `details.policyDenialReason` says which rule | | `STORED_CARDS_DISABLED` | 403 | Stored cards are not enabled for the platform | | `CARDS_DISABLED` | 403 | Cards are not enabled for the platform | | `CARDHOLDER_INFO_MISSING` | 400 | The cardholder record lacks fields a card needs. `details.missingFields` lists them; supply them through the customers API | | `CARDHOLDER_BANK_ACCOUNT_NOT_OPEN` | 400 | The cardholder's USD bank account is not open yet, so no card can be issued until it is | | `CARDHOLDER_COUNTRY_NOT_SUPPORTED` | 400 | The cardholder's address is outside the United States, where agent cards are not offered yet | | `CARDHOLDER_HOLDS_CARD` | 409 | The cardholder already holds a card and the platform allows one per cardholder. Close it before issuing another | | `INVOICE_SUB_SAT_AMOUNT` | 400 | The Lightning invoice's amount is not a whole number of satoshis | | `INVOICE_FUNDS_DEPOSIT` | 400 | The Lightning invoice was issued by Lightspark to fund a deposit and cannot be paid with a send | | `INVOICE_FUNDS_OWN_DEPOSIT` | 400 | The Lightning invoice funds a deposit of the sender's own. Quote a transfer between the customer's accounts instead | example: AGENT_POLICY_DENIED AgentPolicyDenialReason: type: string description: > Which agent policy rule denied executing a quote or issuing a purchase card. Sent as `details.policyDenialReason` with refusal reason `AGENT_POLICY_DENIED` or `AGENT_PURCHASE_CARD_POLICY_DENIED`. Treat it as an open set, not a fixed list: Grid may add values. | Reason | Description | |--------|-------------| | `INVALID_AMOUNT` | The amount is not one the policy can evaluate | | `AGENT_PAUSED` | The agent is paused | | `PERMISSION_MISSING` | The policy lacks `EXECUTE_QUOTES` | | `ACCOUNT_NOT_ALLOWED` | The policy does not allow the source account | | `PER_TRANSACTION_LIMIT_EXCEEDED` | The amount exceeds the per-transaction limit | | `DAILY_LIMIT_EXCEEDED` | The amount would exceed the daily spending limit | | `MONTHLY_LIMIT_EXCEEDED` | The amount would exceed the monthly spending limit | | `DAILY_TRANSACTION_LIMIT_EXCEEDED` | The agent has made its daily number of transactions | | `POOL_LIMIT_EXCEEDED` | The amount would exceed a limit of the agent's spending pool | | `POOL_PAYMENT_TYPE_NOT_ALLOWED` | The agent's spending pool does not allow this kind of payment | example: DAILY_LIMIT_EXCEEDED SweepRuleDestinationRequest: title: Sweep Rule Destination Request type: object description: The account a rule-based account sweeps its incoming payments to. required: - accountId properties: accountId: type: string description: >- Reference to the account that receives the swept funds. May be an external account or another internal account, but never a `RULE_BASED` internal account — that account's own rule would sweep the funds on again. The destination may be denominated in a different currency, in which case the sweep is converted at the prevailing rate. example: ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965 paymentRail: description: >- The payment rail to use when sweeping to an external account. Must be one of the rails supported by the destination account. If omitted, a rail is selected automatically for each sweep. Not accepted when the destination is an internal account, which settles without a payment rail. allOf: - $ref: '#/components/schemas/PaymentRail' 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 PlatformFeeOverride: type: object description: >- Overrides the platform-collected fee for this transaction. When present, it replaces any configured platform-collected fees that would otherwise apply to the transaction. The fixed fee must be denominated in the quote's source currency. required: - platformFixedFee - platformVariableFeeBps properties: platformFixedFee: $ref: '#/components/schemas/FixedFee' description: >- Fixed fee charged for this transaction. Must be denominated in the quote's source currency. platformVariableFeeBps: type: integer minimum: 0 maximum: 10000 description: >- Variable fee in basis points (1 bps = 0.01%) to apply to the transaction's source-currency amount. example: 30 example: platformFixedFee: amount: 50 currency: USD platformVariableFeeBps: 30 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 PaymentUsdAccountInfo: title: USD Bank Account allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/UsdAccountInfo' - type: object required: - reference properties: reference: type: string description: >- Reference code for the payment. On a quote's `paymentInstructions`, include it with the payment, in the memo or remittance information, so Grid can match the payment to the quote. On an internal account's `fundingPaymentInstructions`, the account number is unique to that account and deposits are credited by account number, so the payer doesn't need to include the reference. 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 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 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 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 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 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 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' 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 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 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 PaymentSolanaWalletInfo: title: Solana Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/SolanaWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' PaymentEthereumWalletInfo: title: Ethereum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/EthereumWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' 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 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 PaymentArbitrumWalletInfo: title: Arbitrum Wallet allOf: - $ref: '#/components/schemas/BasePaymentAccountInfo' - $ref: '#/components/schemas/ArbitrumWalletInfo' - type: object properties: assetType: $ref: '#/components/schemas/StablecoinAssetType' 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 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 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} SweepRuleDestination: title: Sweep Rule Destination type: object description: Where a rule-based account's credits are swept. required: - accountId properties: accountId: type: string description: The account that receives the swept funds. example: ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123 paymentRail: allOf: - $ref: '#/components/schemas/PaymentRail' description: >- The rail each sweep is sent over. Null when a rail is selected automatically per sweep, in which case none is resolved ahead of time. example: ACH 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 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 FixedFee: type: object description: Fixed fee charged per transaction. required: - amount - currency properties: amount: type: integer format: int64 minimum: 0 maximum: 9007199254740991 description: >- Fee amount in the smallest unit of the fixed fee's `currency` (e.g., cents for USD). example: 100 currency: type: string description: >- Three-letter currency code (ISO 4217) the fixed fee is denominated in. Some cryptocurrencies may use their own ticker symbols (e.g. "BTC" for Bitcoin, "USDC" for USDC, etc.) example: USD BasePaymentAccountInfo: type: object required: - accountType properties: accountType: $ref: '#/components/schemas/PaymentAccountType' 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 EurAccountInfo: allOf: - $ref: '#/components/schemas/EurAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SEPA - SEPA_INSTANT SwiftAccountInfo: allOf: - $ref: '#/components/schemas/SwiftAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SWIFT MxnAccountInfo: allOf: - $ref: '#/components/schemas/MxnAccountInfoBase' - type: object required: - paymentRails properties: paymentRails: type: array items: type: string enum: - SPEI SparkWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SPARK_WALLET address: type: string description: Spark wallet address example: spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu SolanaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - SOLANA_WALLET address: type: string description: Solana wallet address example: 4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg StablecoinAssetType: type: string description: Type of asset enum: - USDC - USDT EthereumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ETHEREUM_WALLET address: type: string description: Ethereum L1 wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' BaseWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - BASE_WALLET address: type: string description: Base eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' PolygonWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - POLYGON_WALLET address: type: string description: Polygon eth wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' ArbitrumWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - ARBITRUM_WALLET address: type: string description: Arbitrum wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' TronWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - TRON_WALLET address: type: string description: Tron wallet address example: TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL PlasmaWalletInfo: type: object required: - address - accountType properties: accountType: type: string enum: - PLASMA_WALLET address: type: string description: Plasma wallet address example: '0xAbCDEF1234567890aBCdEf1234567890ABcDef12' 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 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 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 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' 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' 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.