Prerequisites
- Obtain developer console access before creating a test project and issuing a key. The console is behind a separate access gate. Use your own project UUID and a
gol_test_...key withproject:read,accounts:read,mandates:read,mandates:write,actions:submit, andwebhooks:managefor this complete flow. Keep the key server-only. A live key is refused. - Use Node.js 22 or later and an ESM TypeScript application. Install the exact preview and both required optional peers explicitly:
- Connect an owner-controlled wallet advertising Wallet Standard
solana:devnetandsolana:signTransaction. Keep its keys in the wallet. This requirement is not a claim that any particular wallet/device is qualified. - Fund the owner with devnet SOL for setup fees, account rent, and later owner safety actions using the Solana faucet. Obtain devnet USDC from the Circle faucet, selecting Solana Devnet. Confirm the mint is
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDUand the owner’s canonical associated token account exists and is not frozen. USDC uses six decimals:100000is 0.1 USDC. Fund enough for the reviewed payment total and gas allowance, not just the first payment. - Choose a separate test agent public key and recipient wallet address. The recipient’s canonical USDC token account must also exist and be usable. Prepare it separately before an execution. An agent signs execution locally; it does not hold the owner’s key. No owner, agent, or private RPC credential belongs in a browser bundle or in GOL’s API.
latest and next resolve to SDK 0.9.0. Pin the preview version rather than using an unversioned install. If adding this to an existing Base application, isolate its dependency as a separate package so the root SDK resolution stays intact.
Check the server connection
SetGOL_TEST_API_KEY, GOL_PROJECT_ID, and GOL_OWNER_ADDRESS through your server’s environment or secret store. The owner address and project ID are public identities; the API key is secret. Do not use a NEXT_PUBLIC_ variable for it.
configuration() verifies the devnet network, program identities, versions, and asset. The API owner snapshot is useful for display; the independent RPC read below supplies the signing context. Wire a browser SolanaClient to the same-origin proxy before continuing.
Prepare the exact owner review
Keep the original intent separately from the API response. This example permits 0.1 USDC per payment and 0.5 USDC in total for one hour. Gas consent adds the configuration’s gas allowance separately; show its per-action cap, total cap, conversion rate, and fee recipient to the owner. Existing delegated/grant headroom is also carried forward separately from this new mandate’s budget.readDevnetOwner checks genesis and validates program-owned accounts, PDAs, sizes, discriminators, versions, owner/mint/engine identities, token balance, delegate and allowance at finalized. setupContext computes expected approval and grant amounts from that independent snapshot. verifyPreparedMandate recomputes terms, policy, gas consent and IDs and checks the complete instruction list, account privileges, signers and fee payer. Any mismatch stops the flow. It accepts the legacy messages this preview API prepares; lookup-table or alternate-message signing is not supported.
Show the original limits, exact total SPL approval, exact grant cap and expiry, carry-forward amounts, rent payer, gas consent and both transactions. Refresh expired reviews or changed wallet/state rather than modifying verified bytes. Simulation is a preflight, not a guarantee of later success or finality. Use bounded retry/backoff for RPC throttling; never open a wallet prompt after a failed check.
Sign the batch and confirm
After the owner explicitly accepts the review, use a connected Wallet Standard signing feature. The account must advertise devnet. This function accepts that feature’ssignTransaction method and invokes it once with two inputs. A wallet can render the batch differently; actual prompt/display qualification is still pending.
confirmMandate can return 202 while observation is pending; a confirmed draft means both setup transactions were observed at finalized commitment. Store the draft ID and signatures so a timeout resumes observation instead of creating another mandate. Read client.mandate(mandateId) and independently inspect the resulting state before executing.
Partial setup cleanup
The batch is not atomic. Transaction 1 approves the SPL delegate and creates/widens an engine grant. Transaction 2 creates the mandate and optional gas policy. If only transaction 1 succeeds, authority remains installed even though this mandate was not created. Check each transaction’s signature/state and read the owner state independently. Revoke the engine grant or SPL delegate before starting another review; these broader controls can affect other mandates sharing that grant/token account. Use the direct safety example withrevoke_grant or spl_revoke, a fresh devnet blockhash, successful simulation, and an owner wallet signature. Confirm the cleanup at finalized commitment and reread readDevnetOwner. SPL revoke is a disconnect: approving again can reconnect older active grants. Use bump_epoch or engine invalidate when permanent invalidation is intended. A timeout alone does not prove either transaction failed. Never blindly sign a second setup batch.