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

# Global Accounts

> Give your customers a branded, self-custodial multi-currency account powered by Grid.

![Global Accounts hero](https://mintcdn.com/agents-docs/qL8kqlSYbvexR8cg/images/heroes/hero-gga.webp?fit=max\&auto=format\&n=qL8kqlSYbvexR8cg\&q=85\&s=7b06f961ed28d727d2de1d2a120c6dc9)

A Global Account is what we consider a programmable, self-custodial account for holding and moving money. Under the hood, it is an embedded [Spark](https://spark.money) wallet that Lightspark provisions for your customer. It can hold different stablecoins, including those denominated in local currencies, as well as other digital assets such as Bitcoin.

In the API, a Global Account is an internal account with `type: "EMBEDDED_WALLET"`. It uses the same customer, quote, transaction, and webhook primitives as other accounts. Receiving funds works the same way, too. To move money out, the customer must authorize the transfer on their device, which signs the payment with a session signing key.

## Why a Global Account?

* **Self-custodial.** Neither Lightspark nor your platform can move funds unilaterally. Outbound transfers require authorization from the customer's device.
* **Stablecoin-denominated.** Balances can be held in stablecoins like [Brale-issued USDB](https://brale.xyz/stablecoins/USDB). You can also issue your own stablecoin and [request enablement in Grid](https://agents-docs.lightspark.com/api-reference/stablecoins/request-grid-enablement-for-a-stablecoin.md). Use the `/quotes` API to convert from fiat or withdraw through supported payment rails.
* **Native.** Reuse the customer, internal-account, quote, transaction, and webhook primitives you already use for payouts or P2P. Global Accounts add authentication and signing at the account level.

## Payment flow

Global Accounts use the same `/quotes` and `/quotes/{id}/execute` pattern as other payments. Outbound transfers also require a client signature.

* **Incoming funds.** Funding an account works like any other internal account. Create a quote with the Global Account as the `destination`, execute it, and Grid converts the source currency into USDB and credits the account. Incoming funds do not require customer approval.
* **Outgoing funds.** Withdrawals and transfers out require the customer to authorize them on their device. Grid returns a `payloadToSign` in the quote's `paymentInstructions`; the client signs those bytes with its session signing key and passes the base64 signature as the `Grid-Wallet-Signature` header on `/quotes/{id}/execute`. Only then does Grid release the funds.

Sessions are short-lived (15 minutes by default) and bound to a specific device via the client key pair, so a stolen signature can't be replayed from a different device or after the session expires. Standard transaction webhooks fire throughout the lifecycle. See [Transaction lifecycle](https://agents-docs.lightspark.com/platform-overview/core-concepts/transaction-lifecycle.md).

## Architecture

Three parties participate in every signed action:

| Party | Role |
| - | - |
| **Client** | The customer's device (browser, iOS app, or Android app). Generates the client key pair, runs WebAuthn, holds the session signing key, and signs outbound requests. |
| **Integrator backend** | Your server. Holds your Grid API credentials, brokers every call to Grid on behalf of the client, and issues WebAuthn challenges for initial passkey registration. |
| **Grid** | Verifies auth credentials, issues sessions bound to the client's public key, and enforces that every account action is authorized. |

The client **never** talks to Grid directly. Every request flows client → integrator backend → Grid.

## Auth credentials, client keys, and session signing keys

Three distinct pieces of crypto collaborate to authorize actions on the Global Account (withdrawals, credential changes, session revocations, wallet exports, and wallet privacy updates):

| Piece | Where it lives | How long it lives | What it proves |
| - | - | - | - |
| **Auth credential**: passkey, OIDC token, or email OTP | Registered on the account; the passkey itself lives on the authenticator, OIDC on your IdP, OTP in the user's inbox | Until the customer revokes it | *"I am the human who owns this account."* Used to authenticate the user at the start of each session. |
| **Client key pair** (P-256) | Generated on the client device for each session-issuing or export request; private key stays in device-local secure storage | One authentication, session refresh, or wallet export | Binds a session or wallet export to the exact device that asked for it. For a session, its private key is the session signing key. For a wallet export, Grid encrypts the credentials to its public key, so only this device can decrypt them. |
| **Session signing key** (P-256) | The private key of the client key pair that issued the session; held on the device for the session's lifetime | 15 minutes (default) | *"This specific account action was approved on an authenticated device."* Builds Grid wallet signatures over the `payloadToSign` Grid returns on quotes, credential changes, session refresh/revocation, wallet exports, sign-in email or phone number changes, and wallet privacy updates. |

The flow is always the same: verify an auth credential with a fresh client key pair → hold its private key as the short-lived session signing key → build a Grid wallet signature over the `payloadToSign` bytes on the client → pass that signature as the `Grid-Wallet-Signature` header on the request that actually moves funds or changes account state. This applies to withdrawals, adding or removing credentials, refreshing or revoking sessions, exporting the wallet seed, changing the sign-in email or phone number, and updating wallet privacy.

## Core capabilities

![](https://agents-docs.lightspark.com/images/icons/wallet1.svg)

Branded dollar accounts

Give each customer a branded account experience backed by Grid account infrastructure.

![](https://agents-docs.lightspark.com/images/icons/coins.svg)

Stablecoin balances

Hold dollar-denominated value and use Grid quotes to move between account balances and supported rails.

![](https://agents-docs.lightspark.com/images/icons/globe.svg)

Local off-ramps

Let customers move value to supported local bank rails, including corridors such as PIX, UPI, SEPA, FPS, and more.

![](https://agents-docs.lightspark.com/images/icons/shield.svg)

Self-custodial authorization

Require customer approval for outbound account actions. Grid and your platform cannot unilaterally move customer funds.

![](https://agents-docs.lightspark.com/images/icons/bitcoin.svg)

Built on Spark

Use Spark, a Lightning-compatible Bitcoin L2, to support Bitcoin and stablecoin flows where enabled for your platform.

![](https://agents-docs.lightspark.com/images/icons/bell.svg)

Webhooks and reconciliation

Track funding, withdrawals, and settlement status with standard Grid account and transaction webhooks.

## Additional capabilities

Some Global Accounts capabilities require platform enablement before you can build with them. [Book a demo](https://www.lightspark.com/contact) to see how they fit your platform.

![](https://agents-docs.lightspark.com/images/icons/credit-card1.svg)

Card programs

Issue cards tied to Global Account balances where enabled for your platform.

![](https://agents-docs.lightspark.com/images/icons/agent.svg)

Agentic payments

Support bounded account access for AI agents with policy-controlled movement.

![](https://agents-docs.lightspark.com/images/icons/IconSquareChecklistMagnifyingGlass.svg)

Advanced account controls

Configure limits, permissions, and controls for more complex account programs.

## Where to next

> [card] [Implementation overview](https://agents-docs.lightspark.com/global-accounts/implementation-overview.md)
>
> End-to-end walkthrough: create a customer, register a passkey, fund the account, and execute a signed withdrawal.

> [card] [Authentication](https://agents-docs.lightspark.com/global-accounts/authentication.md)
>
> Passkey, OAuth (OIDC), and email OTP registration and reauthentication flows.

> [card] [Client keys & signing](https://agents-docs.lightspark.com/global-accounts/client-keys.md)
>
> Generate the P-256 key pair, hold the session signing key, and sign payloads on Web, iOS, and Android.

> [card] [Sandbox testing](https://agents-docs.lightspark.com/global-accounts/platform-tools/sandbox-testing.md)
>
> The sandbox OTP code, signing with real stamps, and sandbox OIDC token rules that exercise the full request shape without standing up real auth providers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.