Sandbox testing

Run the whole agent account flow in sandbox: create and connect agents, delegate signing, fund the account, approve actions, and simulate card charges

The Grid sandbox runs the agent APIs with simulated money. Policies, spending pools, approvals, device codes and webhooks behave as they do in production. Sandbox simulates the API contract, not the banking rails: settlement timings and failure modes that come from a partner bank cannot be reproduced, so test those paths with small amounts in production.

​

Sandbox setup

1. Go to app.lightspark.com, create an account, and generate sandbox API keys from the dashboard.
2. Ask your Lightspark contact to enable the Agents API for your sandbox platform, and any of spending pools, agent cards, purchase cards, stored cards, claimable payouts and payout runs you want to test.
3. Use the normal base URL, https://api.lightspark.com/grid/2025-10-13, with your sandbox token over HTTP Basic auth.

In sandbox, customers are KYC-approved on creation, and a Global Account is provisioned automatically when your platform has USDB in its supported currencies.

​

End-to-end test

1. Create a customer and find the Global Account

   Follow steps 1 and 2 of the Global Accounts walkthrough.

2. Create and connect an agent

   POST /agents with a policy, then redeem the returned device code with POST /agents/device-codes/redeem as the agent software would. Keep the accessToken as $AGENT_TOKEN. See Creating agents.

3. Delegate signing

   Verify the customer’s email OTP credential to get a session (the sandbox OTP code is always 000000), then create the agent’s delegated key with POST /auth/delegated-keys, stamping each leg with the session key. See Sandbox testing for Global Accounts for the OTP and signing shortcuts.

4. Fund the Global Account

   curl -X POST "$GRID_BASE_URL/sandbox/internal-accounts/InternalAccount:019542f5-b3e7-1d02-0000-000000000002/fund" \
     -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
     -H "Content-Type: application/json" \
     -d '{ "amount": 100000 }'
   

   This credits the account at once and fires the standard INCOMING_PAYMENT webhook.

5. Send under and over the threshold

   As the agent, quote and execute a send below the policy’s approvalThresholds.amount and check it comes back APPROVED. Then send one above it and check it comes back PENDING_APPROVAL and your endpoint receives AGENT_ACTION.PENDING_APPROVAL.

6. Approve, reject and let one expire

   Approve one pending action and reject another with POST /agents/{agentId}/actions/{actionId}/approve and .../reject. Leave a third until its quote expires and check it ends FAILED. Poll each with GET /agents/me/actions/{actionId} as the agent would.

7. Test the edges

   Exceed perTransactionLimit and check the send is refused with 403. Pause the agent with PATCH /agents/{agentId} and check it can no longer act. Retry a create with the same Idempotency-Key and check you get the original back.

​

Simulating card charges

Where your sandbox platform has a card program, charge an agent’s cards with the card simulators. They support card programs where Grid makes authorization decisions. The simulation is accepted with 202 and its result arrives asynchronously, with the usual card webhooks.

curl -X POST "$GRID_BASE_URL/sandbox/cards/Card:019542f5-b3e7-1d02-0000-000000000011/simulate/authorization" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": { "code": "USD" },
    "merchant": { "descriptor": "EXAMPLE STORE", "mcc": "5942", "country": "US" }
  }'

The last three characters of merchant.descriptor (1 to 25 characters) choose the outcome:

Suffix	Outcome
002	Declined, INSUFFICIENT_FUNDS
003	Declined, CARD_NOT_ACTIVE; use against a FROZEN card
005	Delayed pull (about 30 seconds), exercising PENDING to CONFIRMED
006	Pull succeeds but the confirmation reports FAILED
Anything else	Approved

Use them to check how your product shows an agent’s card charges and declines, including charges above the agent’s limits or spending pool. The other simulators under /sandbox/cards/{id}/simulate/... cover clearing, returns, reversals and disputes.

​

Webhooks

All webhooks fire in sandbox. Use POST /webhooks/test to send a signed test event to your endpoint, and see Webhooks for the agent events.

Do not send real money to sandbox addresses, invoices or accounts. They are not real destinations and will not receive funds.

​

Moving to production

1. Swap in production API tokens and ask your Lightspark contact to enable the agent features you use on your production platform.
2. Remove sandbox shortcuts, such as the fixed OTP code, from your client and server code.
3. Configure production webhook endpoints and confirm AGENT_ACTION.PENDING_APPROVAL reaches the customer as a notification.
4. Start agents with conservative policies and small limits.