Development sandbox

grapl runs a dedicated test network for application developers, with a faucet for SOL (Test) and USDG (Test). This is a grapl environment, separate from Solana's official Devnet, Testnet and Mainnet. Test balances are disposable; USDG (Test) is a custom SPL token with no relationship to an official USDG deployment or issuer.

Current connection addressesCopy Anchor Link

Open the grapl application to use the grapl Sandbox. The main application uses this test network; a separate sandbox website is deferred. RPC, WebSocket, faucet and HTTP API service addresses remain as listed below.

DNS, valid HTTPS/WSS and runtime configuration for these backend service addresses were confirmed on October 12, 2026. The sandbox instance and genesis are unchanged. The previous addresses record the endpoints used before migration; they remain here as historical evidence, not a guarantee of permanent aliases. The public UI E2E below records the release and application hostname used for that test.

Read the current sandbox configuration and use its returned rpcUrl and wsUrl. The new configuration and RPC endpoints returned the same identity recorded below. Verify genesis when connecting; a hostname change is not permission to accept a different sandbox identity.

The earlier checks covered HTTPS RPC, WSS slot notifications, finalized faucet claims and balances, idempotent replay, and authenticated API discovery of indexed pools. Requests to the API without a key returned 401. After the indexer correction on October 12, 2026, public discovery returned three pools, including the pool created by the public UI E2E. The receipt-history gap remains explicit; discovery recovery does not establish complete transaction history or historical volume. A successful process health check alone does not establish chain readiness or API freshness.

The transaction E2E used RPC and the faucet directly, without an HTTP API key supplied by the test runner. Its results apply to the tested build and endpoints; the new hostnames were verified separately through HTTPS, network identity checks and a WSS slot notification. The controlled validator restart preserved the tested state without establishing indefinite retention.

RPC and network identityCopy Anchor Link

The GET /v1/sandbox/config contract returns version: 1, network: "grapl-sandbox" and an instanceId UUID. It supplies rpcUrl, wsUrl, genesisHash, programId, usdGTestMint, usdGTestDecimals: 6, and explorerUrl. The current explorer URL is null; applications must not invent a destination when it is absent. scan.sandbox.grapl.io is under development and is not yet an available explorer.

The configuration and RPC independently returned the same genesis shown above before and after the hostname migration. Network identity failures return 503 SANDBOX_NOT_READY. Do not configure an application from historical fixture identities or fall back to Mainnet when sandbox configuration is unavailable. The /health route reports process liveness only.

Before configuring the SDK, query Solana's getGenesisHash and compare the result with the verified deployment identity. Track instanceId as well so the application can identify a replacement sandbox instance. If the values change, stop and obtain the updated deployment identity; do not silently accept a new chain. A genesis hash alone does not describe the reset or retention policy.

See Solana's cluster reference for the roles of its official networks. Selecting Solana Devnet connects to that public cluster, not to the grapl sandbox. The sandbox has its own ledger, genesis, programs and test balances. Devnet SOL does not fund this ledger, and sandbox faucet claims do not appear as Devnet or Mainnet balances.

Wallet and custom RPC compatibilityCopy Anchor Link

Connecting a wallet account does not establish that the wallet can sign for this isolated cluster. Changing the application's RPC also does not automatically change the wallet's own network, simulation service or balance display.

For a direct SDK integration, use this sequence. The completed public UI test used an ephemeral Wallet Standard wallet. Compatibility with external wallet extensions still requires separate validation.

1. Read the sandbox configuration and compare its instanceId and genesis with the published deployment identity. Query getGenesisHash through the configured RPC before proceeding.
2. Configure the application with the exact rpcUrl and wsUrl. The direct SDK client supports an explicit RPC URL and expected genesis; it does not require the optional HTTP API.
3. Use a wallet or signer integration verified for this independent cluster and the prepared v0 transaction format. The deployed browser integration requires signing without automatic broadcasting, so the application can recheck network identity before submission. An integration exposing only signAndSendTransaction does not meet that requirement.
4. Keep simulation, blockhash retrieval, submission and receipt/balance checks on the same verified sandbox RPC. If the wallet rejects the cluster or cannot sign the transaction, stop that flow; selecting Devnet does not make it compatible.

Only follow a wallet's custom-network setup when its own documentation supports independent Solana clusters. Support for another RPC provider on an existing network is not enough. Wallet-specific setup steps and a tested compatibility list remain pending. An ephemeral Wallet Standard test wallet does not establish compatibility with Phantom or other external extensions.

Phantom's official testnet instructions list Solana Devnet and Testnet. They do not establish support for adding this independent cluster. This guide therefore does not provide a Phantom custom-RPC menu path or treat its Testnet Mode as a sandbox connection.

The faucet contract accepts a recipient public key without a recipient signature. Receiving a test allocation alone does not validate that the connected browser wallet can sign subsequent protocol transactions. Use the sandbox RPC to verify test balances, and use an explorer only when the configuration supplies a compatible URL.

Test-asset faucetCopy Anchor Link

The faucet accepts two assets and fixes the amount on the server. Its configuration declares each allocation in faucet.assets; amounts remain decimal strings in base units.

The same base-unit quantity represents different display amounts because the assets have different decimals. Verify the configured test mint and its decimals; a matching symbol alone is not a verified token identity.

Quotas and IP identityCopy Anchor Link

Replaying an existing claim consumes no additional quota. Failed claims still consume quota. A limited request returns 429, a Retry-After header and error.retryAfterSeconds; the current daily-limit response uses a conservative 86,400-second delay. Respect the returned delay.

faucet.ipIdentity declares how the service identifies an IP: connection-peer or trusted-proxy-chain. The verified deployment currently reports connection-peer. Clients behind the same ingress peer therefore share its quota; do not describe this as a separate allowance for each end user's IP. Individual client-IP enforcement requires a configured and tested proxy chain. Clients cannot choose their quota identity with forwarding headers.

Submit and follow a claimCopy Anchor Link

Send POST /v1/faucet/claims to the confirmed faucet origin, with a UUID in the Idempotency-Key header and exactly these body fields:

{
  "wallet": "<recipient public key>",
  "asset": "SOL"
}

Use USDG_TEST to request the test token. Caller-supplied amounts and other extra fields are rejected; the request body limit is 4 KiB.

1. Admission returns 202 while the claim is queued or submitted. The response contains id, status, asset, amountBaseUnits, nullable signature and nullable failureCode.
2. Poll GET /v1/faucet/claims/:id. The four states are queued, submitted, confirmed and failed. A send acknowledgement is not confirmation: confirmed requires finalized transaction metadata with no execution error.
3. Retry an uncertain request with the same key, wallet and asset. It returns the original claim; a terminal replay returns 200. Changing the payload for that key returns 409 IDEMPOTENCY_CONFLICT.
4. A failed claim reports a code such as BLOCKHASH_EXPIRED or TRANSACTION_FAILED. The service does not automatically create a replacement payment. Reconcile the configured genesis, receipt, destination, mint/decimals and resulting balance before presenting success.

The service persists signed transaction bytes before broadcast. Worker recovery checks the same signature and can resend only those bytes. Temporary provider errors defer the claim for reconciliation without creating another payment or consuming additional quota. Retry scheduling is durable, allowing other eligible claims to progress while a failing claim waits. A transport error alone does not make a claim terminal. These retry behaviors have local regression coverage; remote validator restart evidence is described below.

The faucet uses its own service address above. Its interfaces are documented here separately from the published public API Reference, which describes the optional grapl HTTP API.

Use the SDK through RPCCopy Anchor Link

The existing SDK Getting started guide accepts an RPC URL, expected genesis hash, grapl program address and fee payer. Reuse that configuration flow with the verified sandbox values above and a disposable test account. The direct client prepares and simulates unsigned transactions; your application retains wallet signing, submission and confirmation.

The grapl HTTP API remains optional for the direct RPC workflow. The public UI E2E completed its protocol transactions through RPC without an HTTP API key supplied by the test runner. Pool discovery is a separate service; an indexing delay does not change a finalized transaction's on-chain result. See the transaction lifecycle and current protocol status for the implemented boundaries.

Verification and remaining gatesCopy Anchor Link

The public UI E2E ran at the former application address https://sandbox.grapl.io on release 171100677b13cb7eb9875252efce9e8ef1cf27d0. It completed the end-to-end flow in one run, with zero retries, in 4.1 minutes. Publication, CI and deployment of that application release are complete. This verification preceded the backend service hostname migration, deployed with release 278aa46, and the move to the main application at grapl.io. The full E2E evidence remains tied to release 1711006 and its historical hostname; it does not establish a repeated E2E run on the new application origin.

The public UI completed two faucet claims and seven actions: wrap SOL (Test), create a pool, open a position, add liquidity, swap, collect fees and remove liquidity. An ephemeral Wallet Standard test wallet signed the actions against the real VPS RPC and faucet over HTTPS. All nine receipts were independently rechecked at finalized commitment with meta.err: null, together with their exact balance changes. No HTTP API key was supplied by the test runner.

Fee collection returned 2 atoms of USDG (Test) to the wallet. An independent SDK/RPC read checked the position owner and full-range ticks [-443584, 443584]. After withdrawal, both the pool and position liquidity were zero, and both position fee balances were zero. The sandbox instance and genesis remained unchanged.

This test covers a direct CLMM pool with classic SPL tokens, no hook and a disposable test wallet. It does not validate external wallet extensions, all token variants, hooked or curve pools, every SDK capability, Mainnet use or production readiness. Existing claim idempotency, quota and network identity checks remain applicable.

The earlier local UI build had already completed the same lifecycle against the remote backend. Its pool was discovered and listed by separate indexer/API/proxy checks. Discovery of the new public-E2E pool was subsequently verified after the indexer correction on October 12, 2026. A public proxy read returned three pools at observedSlot: 30294, including FiMJg1LvCRrQfet8jGStyB8oC3TX3DutRSFa3XfuQcPX. Current pool snapshots now refresh independently of receipt replay. The journal retains an explicit gap where RPC history was pruned; its cursor was not advanced over that gap. Do not treat recovered discovery as complete transaction history or historical volume.

Earlier remote deployment verification used a disposable recipient and confirmed both faucet allocations: 1 SOL (Test) and 1,000 USDG (Test), with finalized receipts, resulting balances and idempotent replay. It also checked a WSS slot notification, five rejected administrative RPC methods (403), and API pool discovery with and without authentication. Bootstrap verified the loaded executable bytes of the core and six optional hook examples. These infrastructure checks are separate from the public UI E2E above.

A controlled restart of the persistent validator completed on October 12, 2026. The public check at 17:05:26 UTC, after the validator's recorded start at 17:05:11 UTC, confirmed unchanged configuration and genesis, the same 1 SOL (Test) and 1,000 USDG (Test) balances, and both original claims and finalized receipts. The indexer resumed and caught up automatically. This verifies the tested restart of this instance; the public UI lifecycle was verified separately.

A separate, disposable Agave VPS probe preserved its genesis, one-SOL balance and finalized receipt across three stages: initial execution, validator restart and container recreation with a changed IP. That isolated probe used a different ledger and identity; its addresses must not be used to configure this sandbox.

Earlier local evidence dated October 12, 2026 covers seven finalized successful transactions in a private Surfpool fixture: two faucet payments, token creation, pool creation, position creation, liquidity and a swap. Restarting the application services and PostgreSQL preserved network identity, balances, claims, quotas and observer state. These disposable fixture identities are historical evidence, not application configuration.

Restarting that earlier Surfpool runtime changed its genesis while preserving test balances. The gateway and faucet then returned 503, and the observer stopped adding to the old stream. This negative fixture verified rejection of a changed network identity. It is separate from the successful persistent Agave restart above.

The sandbox is intended for testing integrations. These checks do not establish uptime guarantees, indefinite state retention, an audit or production readiness.

Reset semanticsCopy Anchor Link

Ordinary restarts retain the instance's identity, program artifacts, ledger and database together; the controlled validator restart above verified preservation of the tested state. The proposed intentional reset procedure stops the old instance, retains its state for diagnosis, and creates a new instance with separate volumes, a new instanceId, authority, test mint and genesis. Replacing only the ledger or reusing the old database with a new chain is not a supported reset.

Applications must re-read configuration and verify the new genesis before reconnecting. Previous balances, transactions, pools, positions and Address Lookup Tables must not be treated as available in the replacement instance; re-fund and recreate the test resources needed for that instance.

The intentional reset procedure remains subject to separate validation; the successful ordinary restart does not validate a reset. A public reset schedule, advance notice, maintenance/status reporting and verified recovery instructions have not been published. Do not assume that service restarts reset the ledger or that test state is retained indefinitely.