docs: add top-level Global Accounts tab

mintlify/docs.json

@@ -72,6 +72,35 @@
           }
         ]
       },
+      {
+        "tab": "Global Accounts",
+        "groups": [
+          {
+            "group": "Overview",
+            "pages": [
+              "global-accounts/index",
+              "global-accounts/implementation-overview"
+            ]
+          },
+          {
+            "group": "Account security",
+            "pages": [
+              "global-accounts/authentication",
+              "global-accounts/client-keys",
+              "global-accounts/managing-sessions",
+              "global-accounts/exporting-wallet"
+            ]
+          },
+          {
+            "group": "Platform tools",
+            "pages": [
+              "global-accounts/platform-tools/webhooks",
+              "global-accounts/platform-tools/sandbox-testing",
+              "global-accounts/platform-tools/postman-collection"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Payouts & B2B",
         "groups": [

mintlify/global-accounts/authentication.mdx

@@ -0,0 +1,10 @@
+---
+title: "Authentication"
+description: "Register, reauthenticate, and manage Global Account credentials (passkey, OAuth, email OTP)"
+icon: "/images/icons/shield.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import Authentication from '/snippets/global-accounts/authentication.mdx';
+
+<Authentication />

mintlify/global-accounts/client-keys.mdx

@@ -0,0 +1,10 @@
+---
+title: "Client keys & signing"
+description: "Generate the P-256 client key pair, decrypt the session signing key, and sign account actions on Web, iOS, and Android"
+icon: "/images/icons/key2.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import ClientKeys from '/snippets/global-accounts/client-keys.mdx';
+
+<ClientKeys />

mintlify/global-accounts/exporting-wallet.mdx

@@ -0,0 +1,10 @@
+---
+title: "Exporting a wallet"
+description: "Let a customer take the seed of their Global Account off Grid"
+icon: "/images/icons/arrow-path-right.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import ExportingWallet from '/snippets/global-accounts/exporting-wallet.mdx';
+
+<ExportingWallet />

mintlify/global-accounts/implementation-overview.mdx

@@ -0,0 +1,10 @@
+---
+title: "Implementation overview"
+description: "End-to-end walkthrough: create a customer, find their Global Account, register a passkey, fund the account, and execute a signed withdrawal."
+icon: "/images/icons/rocket.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import Walkthrough from '/snippets/global-accounts/walkthrough.mdx';
+
+<Walkthrough />

mintlify/global-accounts/index.mdx

@@ -0,0 +1,75 @@
+---
+title: "Global Accounts"
+sidebarTitle: "Introduction"
+description: "Give your customers a branded, self-custody dollar account powered by Grid."
+icon: "/images/icons/wallet1.svg"
+mode: "wide"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import { FeatureCard, FeatureCardGrid } from '/snippets/feature-card.mdx';
+import Concepts from '/snippets/global-accounts/concepts.mdx';
+
+<img
+  src="/images/heroes/hero-gga.webp"
+  alt="Grid Global Accounts hero"
+  className="page-hero"
+/>
+
+<Concepts />
+
+## Core capabilities
+
+<FeatureCardGrid cols={3}>
+  <FeatureCard icon="/images/icons/wallet1.svg" title="Branded dollar accounts">
+    Give each customer a branded account experience backed by Grid account infrastructure.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/coins.svg" title="Stablecoin balances">
+    Hold dollar-denominated value and use Grid quotes to move between account balances and supported rails.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/globe.svg" title="Local off-ramps">
+    Let customers move value to supported local bank rails, including corridors such as PIX, UPI, SEPA, FPS, and more.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/shield.svg" title="Self-custody authorization">
+    Require customer approval for outbound account actions. Grid and your platform cannot unilaterally move customer funds.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/bitcoin.svg" title="Built on Spark">
+    Use Spark, a Lightning-compatible Bitcoin L2, to support Bitcoin and stablecoin flows where enabled for your platform.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/bell.svg" title="Webhooks and reconciliation">
+    Track funding, withdrawals, and settlement status with standard Grid account and transaction webhooks.
+  </FeatureCard>
+</FeatureCardGrid>
+
+## 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.
+
+<FeatureCardGrid cols={3}>
+  <FeatureCard icon="/images/icons/credit-card1.svg" title="Card programs">
+    Issue cards tied to Global Account balances where enabled for your platform.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/agent.svg" title="Agentic payments">
+    Support bounded account access for AI agents with policy-controlled movement.
+  </FeatureCard>
+  <FeatureCard icon="/images/icons/IconSquareChecklistMagnifyingGlass.svg" title="Advanced account controls">
+    Configure limits, permissions, and controls for more complex account programs.
+  </FeatureCard>
+</FeatureCardGrid>
+
+## Where to next
+
+<CardGroup cols={2}>
+  <Card title="Implementation overview" href="/global-accounts/implementation-overview" icon="rocket">
+    End-to-end walkthrough: create a customer, register a passkey, fund the account, and execute a signed withdrawal.
+  </Card>
+  <Card title="Authentication" href="/global-accounts/authentication" icon="shield-check">
+    Passkey, OAuth (OIDC), and email OTP registration and reauthentication flows.
+  </Card>
+  <Card title="Client keys & signing" href="/global-accounts/client-keys" icon="key">
+    Generate the P-256 key pair, decrypt the session signing key, and sign payloads on Web, iOS, and Android.
+  </Card>
+  <Card title="Sandbox testing" href="/global-accounts/platform-tools/sandbox-testing" icon="hammer">
+    Magic values for OTP, signatures, and OAuth tokens that exercise the full request shape without standing up real auth providers.
+  </Card>
+</CardGroup>

mintlify/global-accounts/managing-sessions.mdx

@@ -0,0 +1,10 @@
+---
+title: "Sessions"
+description: "List and revoke active sessions on a Global Account"
+icon: "/images/icons/arrows-repeat-circle.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import Sessions from '/snippets/global-accounts/managing-sessions.mdx';
+
+<Sessions />

mintlify/global-accounts/platform-tools/postman-collection.mdx

@@ -0,0 +1,10 @@
+---
+title: "Postman Collection"
+description: "Explore the Grid API for Global Accounts using the published Postman collection"
+icon: "/images/icons/IconPostman.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import PostmanCollection from '/snippets/postman-collection.mdx';
+
+<PostmanCollection />

mintlify/global-accounts/platform-tools/sandbox-testing.mdx

@@ -0,0 +1,63 @@
+---
+title: "Sandbox testing"
+description: "Exercise the Global Account auth, signing, and funding flows without standing up real OTP delivery, WebAuthn, or OIDC providers"
+icon: "/images/icons/hammer.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import SandboxGlobalAccountMagic from '/snippets/sandbox-global-account-magic.mdx';
+
+The Grid sandbox lets you exercise the full Global Accounts integration — customer creation, account lookup, credential registration, funding, and signed withdrawals — without moving real money or standing up real auth providers. All API endpoints work the same way as in production, but money movements are simulated and real auth checks are bypassed via a small set of magic values.
+
+## Sandbox setup
+
+To use the sandbox environment:
+
+1. Go to [app.lightspark.com](https://app.lightspark.com), create an account, and generate your sandbox API keys from the dashboard.
+2. Add your sandbox API token and secret to your environment variables.
+3. Use the normal production base URL: `https://api.lightspark.com/grid/2025-10-13`.
+4. Authenticate using your sandbox token with HTTP Basic Auth.
+
+In sandbox, customers are KYC-approved on creation, and a Global Account is provisioned automatically alongside any other internal accounts whenever the platform has `USDB` in its supported currencies.
+
+## Funding a Global Account
+
+Real Global Accounts are funded by following payment instructions or by executing a quote into the account. In sandbox, you can instantly add USDB to any internal account using the sandbox funding endpoint:
+
+```bash
+curl -X POST "$GRID_BASE_URL/sandbox/internal-accounts/InternalAccount:abc123/fund" \
+  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "amount": 100000
+  }'
+```
+
+This credits the account immediately and fires the standard `INCOMING_PAYMENT` webhook. Use this to skip straight to a funded state when you're testing withdrawals.
+
+## Magic values
+
+<SandboxGlobalAccountMagic />
+
+## Webhooks
+
+All webhook events fire normally in sandbox. Configure your webhook URL in the dashboard, perform any signed action, and your endpoint receives the same `INCOMING_PAYMENT`, `OUTGOING_PAYMENT`, and account-state events as production.
+
+<Warning>
+  Do not try to send real money to any sandbox addresses or accounts. These are not real destinations and will not receive funds.
+</Warning>
+
+## Moving to production
+
+When you're ready to go live:
+
+1. Generate production API tokens in the dashboard and swap them for the sandbox credentials in your environment.
+2. Remove any sandbox magic values from your client and server code — production runs the real OTP, HPKE, WebAuthn, and ECDSA flows.
+3. Configure production webhook endpoints.
+4. Test with small amounts first.
+
+## Next steps
+
+- [Implementation overview](/global-accounts/implementation-overview) — end-to-end walkthrough of the happy path.
+- [Authentication](/global-accounts/authentication) — per-credential-type registration and reauthentication flows.
+- [Webhooks](/global-accounts/platform-tools/webhooks) — event handling reference.

mintlify/global-accounts/platform-tools/webhooks.mdx

@@ -0,0 +1,10 @@
+---
+title: "Webhooks"
+description: "Receive webhook events for funding, withdrawals, and other account state changes on Global Accounts"
+icon: "/images/icons/bell.svg"
+"og:image": "/images/og/og-global-accounts.webp"
+---
+
+import Webhooks from '/snippets/webhooks.mdx';
+
+<Webhooks />

mintlify/global-p2p/global-accounts/overview.mdx

@@ -5,6 +5,8 @@ description: "Self-custody stablecoin accounts that plug into Grid payment flows
 icon: "/images/icons/crypto-wallet.svg"
 ---
 
-import Overview from '/snippets/global-accounts/overview.mdx';
+import Concepts from '/snippets/global-accounts/concepts.mdx';
+import Walkthrough from '/snippets/global-accounts/walkthrough.mdx';
 
-<Overview />
+<Concepts />
+<Walkthrough />

mintlify/payouts-and-b2b/global-accounts/overview.mdx

@@ -5,6 +5,8 @@ description: "Self-custody stablecoin accounts that plug into Grid payment flows
 icon: "/images/icons/crypto-wallet.svg"
 ---
 
-import Overview from '/snippets/global-accounts/overview.mdx';
+import Concepts from '/snippets/global-accounts/concepts.mdx';
+import Walkthrough from '/snippets/global-accounts/walkthrough.mdx';
 
-<Overview />
+<Concepts />
+<Walkthrough />

mintlify/ramps/global-accounts/overview.mdx

@@ -5,6 +5,8 @@ description: "Self-custody stablecoin accounts that plug into Grid payment flows
 icon: "/images/icons/crypto-wallet.svg"
 ---
 
-import Overview from '/snippets/global-accounts/overview.mdx';
+import Concepts from '/snippets/global-accounts/concepts.mdx';
+import Walkthrough from '/snippets/global-accounts/walkthrough.mdx';
 
-<Overview />
+<Concepts />
+<Walkthrough />

mintlify/rewards/global-accounts/overview.mdx

@@ -5,6 +5,8 @@ description: "Self-custody stablecoin accounts that plug into Grid payment flows
 icon: "/images/icons/crypto-wallet.svg"
 ---
 
-import Overview from '/snippets/global-accounts/overview.mdx';
+import Concepts from '/snippets/global-accounts/concepts.mdx';
+import Walkthrough from '/snippets/global-accounts/walkthrough.mdx';
 
-<Overview />
+<Concepts />
+<Walkthrough />

mintlify/snippets/global-accounts/concepts.mdx

@@ -0,0 +1,41 @@
+A Grid Global Account is powered by a self-custody embedded [Spark](https://spark.money) wallet Grid provisions for your customer that holds a stablecoin or BTC balance and participates in the standard Grid payment flows. It behaves like any other internal account for *incoming* funds, but every outbound transfer must be authorized by the customer — a session signing key issued for their device signs each payment. In the API, a Global Account is an internal account with `type: "EMBEDDED_WALLET"` that participates in the standard Grid customer, quote, transaction, and webhook flows.
+
+## Why a Grid Global Account?
+
+- **Self-custody.** Grid never has unilateral access to move user funds, and neither do you. The customer's device is the only party that can authorize a transaction.
+- **Stablecoin-denominated.** Balances are held as stablecoins like [Brale-issued USDB](https://brale.xyz/stablecoins/USDB). Use the standard `/quotes` API to convert in from fiat or out to any supported Grid bank-account rail (ACH, PIX, CLABE, UPI, IBAN, UMA, …).
+- **Grid-native.** You reuse the customer, internal-account, quote, transaction, and webhook primitives you already integrated for Payouts or P2P. The only thing that's new is an auth + signing layer at the account.
+- **Built on Bitcoin.** Global Accounts run on Spark, a Lightning-compatible Bitcoin L2 that supports instant, low-fee Bitcoin and Stablecoin transfers. You get the benefits of running on Bitcoin, the most neutral, decentralized, and secure network for money.
+
+## Payment flow
+
+Grid Global Accounts ride on the same `/quotes` + `/quotes/{id}/execute` pattern as every other Grid payment. The only thing that's different is that outbound transfers need 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. No customer approval needed — incoming value is passive.
+- **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](/platform-overview/core-concepts/transaction-lifecycle).
+
+## 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, decrypts 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 session signing keys (encrypted 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, and wallet exports):
+
+| 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 verification request; private key stays in device-local secure storage | One verification request | Binds a given session signing key delivery to the exact device that asked for it — Grid encrypts the session to this public key, so only this device can decrypt. |
+| **Session signing key** (P-256) | Issued by Grid, sealed to the client public key, decrypted and held on the device for the session's lifetime | 15 minutes (default) | *"This specific account action was approved on an authenticated device."* Signs the `payloadToSign` Grid returns on quotes, credential changes, session revocations, and wallet exports. |
+
+The flow is always the same: verify an auth credential → receive a short-lived session signing key → sign `payloadToSign` bytes on the client → pass the 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, revoking sessions, and exporting the wallet seed.