Update internal account

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.

PATCH /internal-accounts/{id}

cURL

cURL

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/internal-accounts/{id} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "privateEnabled": true
}
'

import LightsparkGrid from '@lightsparkdev/grid';

const client = new LightsparkGrid({
  username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted
  password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted
});

const internalAccount = await client.customers.updateInternalAccount(
  'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
  { InternalAccountUpdateRequest: {} },
);

console.log(internalAccount.id);

package com.lightspark.grid.example

import com.lightspark.grid.client.LightsparkGridClient
import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient
import com.lightspark.grid.models.customers.CustomerUpdateInternalAccountParams
import com.lightspark.grid.models.customers.InternalAccountUpdateRequest
import com.lightspark.grid.models.sandbox.internalaccounts.InternalAccount

fun main() {
    val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv()

    val params: CustomerUpdateInternalAccountParams = CustomerUpdateInternalAccountParams.builder()
        .id("InternalAccount:019542f5-b3e7-1d02-0000-000000000002")
        .internalAccountUpdateRequest(InternalAccountUpdateRequest.builder().build())
        .build()
    val internalAccount: InternalAccount = client.customers().updateInternalAccount(params)
}

200

{
  "id": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "type": "EMBEDDED_WALLET",
  "status": "ACTIVE",
  "balance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "totalBalance": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "fundingPaymentInstructions": [],
  "privateEnabled": true,
  "createdAt": "2026-04-08T15:30:00Z",
  "updatedAt": "2026-04-08T15:35:02Z"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"encoding\":\"PAYLOAD_ENCODING_HEXADECIMAL\",\"hashFunction\":\"HASH_FUNCTION_NO_OP\",\"payload\":\"9f3b...\",\"signWith\":\"sp1q...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2\"}",
  "requestId": "Request:019542f5-b3e7-1d02-0000-000000000010",
  "expiresAt": "2026-04-08T15:35:00Z"
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 404,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature · string

Full API-key stamp built over the prior payloadToSign with the session API keypair of a verified authentication credential on the target internal account. Required on the signed retry; ignored on the initial call.

Request-Id · string

The requestId returned in a prior 202 response, echoed back on the signed retry so the server can correlate it with the issued challenge. Required on the signed retry; must be paired with Grid-Wallet-Signature.

Path Parameters

id · string · required

The id of the internal account to update.

Body

application/json

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.

Example:

true

Response

200

application/json

Signed retry accepted. Returns the updated internal account.

id · string · required

The ID of the internal account

Example:

"InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123"

type · enum<string> · 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.

Available options: INTERNAL_FIAT, INTERNAL_CRYPTO, EMBEDDED_WALLET

status · enum<string> · 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.
• 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.

Available options: PENDING, ACTIVE, CLOSED, FROZEN, FAILED

Example:

"ACTIVE"

balance · object · required

The balance available to spend, excluding pending and held funds

Show child attributes

totalBalance · object · required

The total balance, including pending and held funds

Show child attributes

fundingPaymentInstructions · object[] · required

Payment instructions for funding the account

Show child attributes

createdAt · string<date-time> · required

Timestamp when the internal account was created

Example:

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

updatedAt · string<date-time> · required

Timestamp when the internal account was last updated

Example:

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

customerId · string

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"

privateEnabled · boolean

Whether wallet privacy is enabled for the Embedded Wallet. Only present for EMBEDDED_WALLET internal accounts.

Example:

true