---
title: "Update internal account"
method: PATCH
path: "/internal-accounts/{id}"
tags: ["Internal Accounts"]
---

# Update internal account

`PATCH /internal-accounts/{id}`

Update mutable fields on an internal account. Today this supports updating the wallet privacy setting for an Embedded Wallet internal account.

Updating wallet privacy is a two-step signed-retry flow:

1. Call `PATCH /internal-accounts/{id}` with the request body `{ "privateEnabled": true }` and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`.

2. Use the session API keypair of a verified authentication credential on the same internal account to build an API-key stamp over `payloadToSign`, then retry with that full stamp as the `Grid-Wallet-Signature` header and the `requestId` echoed back as the `Request-Id` header. The retry body must carry the same update fields submitted in step 1. The signed retry returns `200` with the updated internal account.

## Headers

- `Grid-Wallet-Signature` string
- `Request-Id` string

## Request body

- InternalAccountUpdateRequest — Partial request body for `PATCH /internal-accounts/{id}`. At least one update field must be provided. On step 1 of the signed-retry flow Grid binds the submitted update fields into `payloadToSign`; on step 2 the client echoes the same fields back and Grid applies the update to the internal account.
  - `privateEnabled` boolean — Whether wallet privacy should be enabled for the Embedded Wallet.

## Response `200`

Signed retry accepted. Returns the updated internal account.

- InternalAccount
  - `id` string, required — The ID of the internal account
  - `customerId` string — The ID of the customer associated with the internal account. If this field is empty, the internal account belongs to the platform.
  - `type` 'INTERNAL_FIAT' | 'INTERNAL_CRYPTO' | 'EMBEDDED_WALLET', required — 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.
  - `status` 'PENDING' | 'ACTIVE' | 'CLOSED' | 'FROZEN', required — 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. - `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.
  - `balance` CurrencyAmount, required
    - `amount` integer, required — Amount in the smallest unit of the currency (e.g., cents for USD/EUR, satoshis for BTC)
    - `currency` Currency, required
      - `code` string — 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.)
      - `name` string — Full name of the currency
      - `symbol` string — Symbol of the currency
      - `decimals` integer — Number of decimal places for the currency
  - `fundingPaymentInstructions` PaymentInstructions[], required — Payment instructions for funding the account
    - `instructionsNotes` string — Additional human-readable instructions for making the payment
    - `isPlatformAccount` boolean — Indicates whether the account is a platform account or a customer account.
    - `accountOrWalletInfo` union, required
      - PaymentUsdAccountInfo
        - `accountType` 'USD_ACCOUNT', required
        - `accountNumber` string, required — The account number of the bank
        - `routingNumber` string, required — The ABA routing number
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentBrlAccountInfo
        - `accountType` 'BRL_ACCOUNT'
        - `qrCode` string, required — 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.
      - PaymentMxnAccountInfo
        - `accountType` 'MXN_ACCOUNT', required
        - `clabeNumber` string, required — The CLABE number of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentDkkAccountInfo
        - `accountType` 'DKK_ACCOUNT', required
        - `iban` string, required — Danish IBAN (18 characters, starting with DK)
        - `swiftCode` string — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentEurAccountInfo
        - `accountType` 'EUR_ACCOUNT', required
        - `iban` string, required — The IBAN of the bank account
        - `swiftCode` string — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentInrAccountInfo
        - `accountType` 'INR_ACCOUNT', required
        - `vpa` string, required — The UPI Virtual Payment Address
        - `paymentRails` string[], required
      - PaymentNgnAccountInfo
        - `accountType` 'NGN_ACCOUNT', required
        - `accountNumber` string, required — Nigerian bank account number
        - `bankName` string, required — The name of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentCadAccountInfo
        - `accountType` 'CAD_ACCOUNT', required
        - `bankCode` string, required — Canadian financial institution number (3 digits)
        - `branchCode` string, required — Transit number identifying the branch (5 digits)
        - `accountNumber` string, required — Bank account number (7-12 digits)
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentGbpAccountInfo
        - `accountType` 'GBP_ACCOUNT', required
        - `sortCode` string, required — The UK sort code
        - `accountNumber` string, required — UK bank account number (8 digits)
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentHkdAccountInfo
        - `accountType` 'HKD_ACCOUNT', required
        - `bankName` string, required — The name of the bank
        - `accountNumber` string, required — Hong Kong bank account number
        - `swiftCode` string, required — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentIdrAccountInfo
        - `accountType` 'IDR_ACCOUNT', required
        - `bankName` string, required — The name of the bank
        - `accountNumber` string, required — Indonesian bank account number
        - `swiftCode` string, required — The SWIFT/BIC code of the bank
        - `phoneNumber` string, required — Indonesian phone number for e-wallet payments
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentMyrAccountInfo
        - `accountType` 'MYR_ACCOUNT', required
        - `bankName` string, required — The name of the bank
        - `accountNumber` string, required — Malaysian bank account number
        - `swiftCode` string, required — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentPhpAccountInfo
        - `accountType` 'PHP_ACCOUNT', required
        - `bankName` string, required — Name of the beneficiary's bank
        - `accountNumber` string, required — Bank account number
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentSgdAccountInfo
        - `accountType` 'SGD_ACCOUNT', required
        - `bankName` string, required — Name of the beneficiary's bank
        - `accountNumber` string, required — Bank account number
        - `swiftCode` string, required — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentThbAccountInfo
        - `accountType` 'THB_ACCOUNT', required
        - `bankName` string, required — The name of the bank
        - `accountNumber` string, required — Thai bank account number
        - `swiftCode` string, required — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentVndAccountInfo
        - `accountType` 'VND_ACCOUNT', required
        - `bankName` string, required — The name of the bank
        - `accountNumber` string, required — Vietnamese bank account number
        - `swiftCode` string, required — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentAedAccountInfo
        - `accountType` 'AED_ACCOUNT', required
        - `iban` string, required — UAE IBAN (23 characters, starting with AE)
        - `swiftCode` string — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentKesAccountInfo
        - `accountType` 'KES_ACCOUNT', required
        - `phoneNumber` string, required — Kenyan mobile money phone number
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentMwkAccountInfo
        - `accountType` 'MWK_ACCOUNT', required
        - `phoneNumber` string, required — The phone number in international format
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentRwfAccountInfo
        - `accountType` 'RWF_ACCOUNT', required
        - `phoneNumber` string, required — Rwandan mobile money phone number
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentTzsAccountInfo
        - `accountType` 'TZS_ACCOUNT', required
        - `phoneNumber` string, required — Tanzanian mobile money phone number
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentUgxAccountInfo
        - `accountType` 'UGX_ACCOUNT', required
        - `phoneNumber` string, required — The phone number in international format
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentXofAccountInfo
        - `accountType` 'XOF_ACCOUNT', required
        - `phoneNumber` string, required — The phone number in international format
        - `provider` string, required — The mobile money provider name
        - `region` 'BJ' | 'CI' | 'SN' | 'TG', required — Country code within the West African CFA franc zone
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentZarAccountInfo
        - `accountType` 'ZAR_ACCOUNT', required
        - `accountNumber` string, required — South African bank account number
        - `bankName` string, required — The name of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentZmwAccountInfo
        - `accountType` 'ZMW_ACCOUNT', required
        - `phoneNumber` string, required — Zambian mobile money phone number
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentBwpAccountInfo
        - `accountType` 'BWP_ACCOUNT', required
        - `phoneNumber` string, required — The phone number in international format
        - `provider` string, required — The mobile money provider name
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentXafAccountInfo
        - `accountType` 'XAF_ACCOUNT', required
        - `phoneNumber` string, required — The phone number in international format
        - `provider` string, required — The mobile money provider name
        - `region` 'CM' | 'CG', required — Country code within the Central African CFA franc zone
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentBdtAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber
        - `accountType` 'BDT_ACCOUNT', required
        - `accountNumber` string — The account number of the bank
        - `branchCode` string — The branch code
        - `swiftCode` string — The SWIFT/BIC code of the bank
        - `phoneNumber` string — The phone number in international format
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentArsAccountInfo
        - `accountType` 'ARS_ACCOUNT', required
        - `accountNumber` string, required — The static CVU (Clave Virtual Uniforme) bank account number to pay to.
      - PaymentCopAccountInfo
        - `accountType` 'COP_ACCOUNT'
        - `paymentUrl` string, uri, required — A payment URL where the customer can complete their COP deposit.
      - PaymentEgpAccountInfo
        - `accountType` 'EGP_ACCOUNT', required
        - `bankName` string, required — The name of the bank
        - `accountNumber` string, required — The account number of the bank
        - `iban` string — Egyptian IBAN (29 characters, starting with EG)
        - `swiftCode` string — The SWIFT/BIC code of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentGhsAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: phoneNumber
        - `accountType` 'GHS_ACCOUNT', required
        - `accountNumber` string — The account number of the bank
        - `phoneNumber` string — The phone number in international format
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentGtqAccountInfo
        - `accountType` 'GTQ_ACCOUNT', required
        - `accountNumber` string, required — The account number of the bank
        - `bankAccountType` 'CHECKING' | 'SAVINGS', required — The bank account type
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentHtgAccountInfo
        - `accountType` 'HTG_ACCOUNT', required
        - `phoneNumber` string, required — The phone number in international format
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentJmdAccountInfo
        - `accountType` 'JMD_ACCOUNT', required
        - `accountNumber` string, required — The account number of the bank
        - `branchCode` string, required — The branch code
        - `bankAccountType` 'CHECKING' | 'SAVINGS', required — The bank account type
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentPkrAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: accountNumber - MOBILE_MONEY: bankName, phoneNumber
        - `accountType` 'PKR_ACCOUNT', required
        - `accountNumber` string — The account number of the bank
        - `iban` string — Pakistani IBAN (24 characters, starting with PK)
        - `phoneNumber` string — The phone number in international format
        - `bankName` string — The name of the bank
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentSlvAccountInfo — Required fields depend on the selected paymentRails: - BANK_TRANSFER: bankAccountType, accountNumber - MOBILE_MONEY: phoneNumber
        - `accountType` 'SLV_ACCOUNT', required
        - `bankName` string — The name of the bank (BANK_TRANSFER only)
        - `accountNumber` string — The account number of the bank (BANK_TRANSFER only)
        - `bankAccountType` 'CHECKING' | 'SAVINGS' — The bank account type (BANK_TRANSFER only)
        - `phoneNumber` string — The phone number in international format (MOBILE_MONEY only — e.g. Tigo Money)
        - `paymentRails` string[], required
        - `reference` string, required — Unique reference code that must be included with the payment to properly credit it
      - PaymentSparkWalletInfo
        - `accountType` 'SPARK_WALLET', required
        - `address` string, required — Spark wallet address
        - `assetType` 'BTC' | 'USDB', required — Type of asset
        - `invoice` string — Invoice for the payment
      - PaymentLightningInvoiceInfo
        - `accountType` 'LIGHTNING'
        - `invoice` string, required — Invoice for the payment
      - PaymentSolanaWalletInfo
        - `accountType` 'SOLANA_WALLET', required
        - `address` string, required — Solana wallet address
        - `assetType` 'USDC' | 'USDT' — Type of asset
      - PaymentTronWalletInfo
        - `accountType` 'TRON_WALLET', required
        - `address` string, required — Tron wallet address
        - `assetType` 'USDT' — Type of asset
      - PaymentPolygonWalletInfo
        - `accountType` 'POLYGON_WALLET', required
        - `address` string, required — Polygon eth wallet address
        - `assetType` 'USDC' — Type of asset
      - PaymentBaseWalletInfo
        - `accountType` 'BASE_WALLET', required
        - `address` string, required — Base eth wallet address
        - `assetType` 'USDC' — Type of asset
      - PaymentEthereumWalletInfo
        - `accountType` 'ETHEREUM_WALLET', required
        - `address` string, required — Ethereum L1 wallet address
        - `assetType` 'USDC' — Type of asset
      - PaymentEmbeddedWalletInfo
        - `accountType` 'EMBEDDED_WALLET', required — Discriminator value identifying this as Embedded Wallet payment instructions.
        - `payloadToSign` string, required — 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 Turnkey API-key stamp is passed as the `Grid-Wallet-Signature` header on `POST /quotes/{quoteId}/execute` to authorize the outbound transfer from the wallet.
  - `privateEnabled` boolean — Whether wallet privacy is enabled for the Embedded Wallet. Only present for `EMBEDDED_WALLET` internal accounts.
  - `createdAt` string, date-time, required — Timestamp when the internal account was created
  - `updatedAt` string, date-time, required — Timestamp when the internal account was last updated

## Other responses

- `202` — Challenge issued. The response contains `payloadToSign` (which binds the submitted update fields) plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair and echo `requestId` on the retry.
- `400` — Bad request
- `401` — Unauthorized. Returned when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match a pending internal account update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call.
- `404` — Internal account not found
- `500` — Internal service error

---

[API](https://skmtc.net/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.net/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/versions/d0bce562bffd/schema)