docs: document real sandbox wallet signatures

[DhruvPareek]

Summary

• Document sandbox signed wallet actions using the decrypted session signing key and a Turnkey API-key stamp over the exact payloadToSign.
• Explain that sandbox validates the P-256 stamp and requires the signing public key to belong to an active sandbox wallet session.
• Update the scripts README sandbox tip while keeping the legacy sandbox-valid-signature compatibility path documented.

Backend Pairing

• Paired with webdev PR #27730 for sandbox Grid-Wallet-Signature validation.
• Paired with webdev PR #27795 so EMAIL_OTP sandbox sessions return decryptable session signing keys.
• Paired with webdev PR #27796 so OAUTH sandbox sessions return decryptable session signing keys.

Testing

• Not run separately; this branch only changes MDX/README prose. The lower docs PR ran npm run build:openapi and npm run lint:openapi.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	May 30, 2026 12:16am

[DhruvPareek]

• docs: document real sandbox wallet signatures #494 👈 (View in Graphite)
• docs: document realistic sandbox passkeys #492
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This docs-only PR upgrades the sandbox wallet signature documentation to reflect that sandbox now validates real P-256 Turnkey API-key stamps (not just the fixed sandbox-valid-signature sentinel), while keeping the legacy compatibility value documented for backwards compatibility.

• sandbox-global-account-magic.mdx: replaces the flat sandbox-valid-signature sentinel description with a full decrypt-then-stamp flow, adds a bash example using $SIGN stamp, and wraps the legacy path in a <Note> callout.
• scripts/README.md: updates the sandbox tip block to accurately describe the new accepted stamp shape and demotes the legacy fixed value to a compatibility footnote.

Confidence Score: 4/5

Safe to merge — changes are prose and code-example only, with no executable logic touched.

The two files are documentation only. The README change is clean and self-contained ($SIGN is defined at line 30 of that file). The MDX snippet introduces a bash example that references $SIGN without any definition or pointer, which leaves API-doc readers with an incomplete, non-runnable example — a usability gap worth addressing before this page goes live.

mintlify/snippets/sandbox-global-account-magic.mdx — the new code example references an unexplained $SIGN variable that is only defined in the scripts README, not in the API documentation context where this snippet is rendered.

Important Files Changed

Filename	Overview
mintlify/snippets/sandbox-global-account-magic.mdx	Replaces fixed sandbox-valid-signature sentinel with real Turnkey API-key stamp flow; $SIGN helper is used in the code example without being defined in this file's context
scripts/README.md	Sandbox tip updated to reflect real stamp acceptance; $SIGN is properly defined at line 30 of this file so the context is self-contained

Sequence Diagram

sequenceDiagram
    participant Client
    participant Grid API
    participant Turnkey Signer

    Client->>Grid API: POST /auth/credentials/{id}/verify (with clientPublicKey)
    Grid API-->>Client: encryptedSessionSigningKey (sealed to clientPublicKey)

    Client->>Client: Decrypt encryptedSessionSigningKey with matching private key → SESSION_PRIV_HEX

    Client->>Grid API: Request signed action (e.g. POST /quotes/{id}/execute)
    Grid API-->>Client: payloadToSign

    Client->>Turnkey Signer: stamp(SESSION_PRIV_HEX, payloadToSign)
    Turnkey Signer-->>Client: P-256 Turnkey API-key STAMP

    Client->>Grid API: Repeat request + Grid-Wallet-Signature: STAMP
    Grid API->>Grid API: Validate stamp is P-256 over pending Turnkey payload and public key belongs to active sandbox session
    Grid API-->>Client: 200 OK

Loading

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
mintlify/snippets/sandbox-global-account-magic.mdx:136
**Undefined `$SIGN` reference in standalone snippet**

The code example uses `$SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN"`, but `$SIGN` is never defined within this MDX file. In `scripts/README.md` it is set at line 30 (`SIGN="node $(pwd)/scripts/embedded-wallet-sign.js"`), so the README context is self-contained. However, this snippet is embedded in API documentation pages where a reader has no pointer to that helper script. Per the style guide, code examples should be "complete, runnable examples that users can copy and execute." A reader unfamiliar with the scripts directory will have no idea what tool to substitute for `$SIGN`.

_{Reviews (1): Last reviewed commit: "docs: document real sandbox wallet signa..." | Re-trigger Greptile}

[greptile-apps]

Undefined $SIGN reference in standalone snippet

The code example uses $SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN", but $SIGN is never defined within this MDX file. In scripts/README.md it is set at line 30 (SIGN="node $(pwd)/scripts/embedded-wallet-sign.js"), so the README context is self-contained. However, this snippet is embedded in API documentation pages where a reader has no pointer to that helper script. Per the style guide, code examples should be "complete, runnable examples that users can copy and execute." A reader unfamiliar with the scripts directory will have no idea what tool to substitute for $SIGN.

Prompt To Fix With AI

This is a comment left during a code review.
Path: mintlify/snippets/sandbox-global-account-magic.mdx
Line: 136

Comment:
**Undefined `$SIGN` reference in standalone snippet**

The code example uses `$SIGN stamp "$SESSION_PRIV_HEX" "$PAYLOAD_TO_SIGN"`, but `$SIGN` is never defined within this MDX file. In `scripts/README.md` it is set at line 30 (`SIGN="node $(pwd)/scripts/embedded-wallet-sign.js"`), so the README context is self-contained. However, this snippet is embedded in API documentation pages where a reader has no pointer to that helper script. Per the style guide, code examples should be "complete, runnable examples that users can copy and execute." A reader unfamiliar with the scripts directory will have no idea what tool to substitute for `$SIGN`.

How can I resolve this? If you propose a fix, please make it concise.

[pengying]

I think this is a good call out?

[pengying]

can you point to the github scripts directory in a call out or something?

[DhruvPareek]

added a note

[pengying]

just a call out link to the github repo where the signing util lives

[DhruvPareek]

Merge activity

• May 30, 12:13 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 30, 12:13 AM UTC: Graphite couldn't merge this pull request because a downstack PR docs: document realistic sandbox passkeys #492 failed to merge.
• May 30, 12:15 AM UTC: A user started a stack merge that includes this pull request via Graphite.
• May 30, 12:17 AM UTC: Graphite rebased this pull request as part of a merge.
• May 30, 12:18 AM UTC: @DhruvPareek merged this pull request with Graphite.

The base branch was changed.

[restamp-bot]

68e27ae is a pure rebase onto 0db50fa. Approving based on @pengying's previous approval of 21ebe61.