docs: crypto refund destination + real-time fee assessment

[ls-bolt]

Summary

Two clarifications to the Grid concept docs, prompted by a real-time USDC funding support case:

• Crypto refund destination (Transaction Lifecycle → Refund Object): a new "Refund destination" subsection explains that where a refund lands depends on how the transaction was funded. Real-time (JIT) quotes funded with crypto are refunded to the customer's internal account balance for that asset — not back to the source wallet — because Grid can't verify the sending wallet belongs to the customer. That balance is reusable via a new quote or POST /transfer-out.
• Real-time fee assessment (Quote System → Fees): a new "How the variable fee is applied" subsection documents how the variable fee is assessed for each locked side:
  • Sending locked: received = send − send × fee → send $50 at 10 bps ⇒ receive $49.95
  • Receiving locked: send = received / (1 − fee) → receive $50 at 10 bps ⇒ send $50.05005005…
  • Plus a note on why receiver-locked divides by (1 − fee) (keeps the effective rate identical across both locked sides) and how FX layers on for cross-currency quotes.

Test plan

• mint broken-links — no broken links or anchors in the edited pages (the new #locked-currency-side link resolves)
• Verified the worked numbers: 50 − 50×0.001 = 49.95, 50 / 0.999 = 50.05005005…
• Additive-only edits to existing pages; no new pages, no navigation changes

[vercel]

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Jul 24, 2026 6:39pm
grid-wallet-demo	Ignored	Preview	Jul 24, 2026 6:39pm

[akanter]

• docs: crypto refund destination + real-time fee assessment #737 👈 (View in Graphite)
• main

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

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jul 24, 2026, 6:40 PM

[greptile-apps]

Greptile Summary

This PR adds two additive documentation sections to the Grid concept docs, prompted by a real-time USDC funding support case. Both additions are mathematically accurate, anchor links resolve, and the prose follows the established Mintlify style guide.

• Refund destination (transaction-lifecycle.mdx): Documents where refunds land for prefunded, instant-fiat, and crypto-funded transactions, including the explanation for why crypto refunds credit an internal balance rather than returning to the source wallet.
• Real-time fee assessment (quote-system.mdx): Documents the variable fee formulas for both SENDING- and RECEIVING-locked quotes with verified worked examples (50 − 50×0.001 = 49.95; 50/0.999 = 50.0500…) and a note on the cross-currency layer.

Confidence Score: 5/5

Additive-only documentation changes with verified math and resolving anchor links — safe to merge.

Both sections are additive prose with no navigation changes. The formulas and worked numbers were independently verified, the #locked-currency-side anchor exists at the expected heading, and POST /transfer-out is consistently referenced across the codebase.

Files Needing Attention: No files require special attention.

Important Files Changed

Filename	Overview
mintlify/platform-overview/core-concepts/quote-system.mdx	Adds 'How the variable fee is applied' subsection with mathematically verified formulas and worked examples for both SENDING- and RECEIVING-locked quotes; no issues found.
mintlify/platform-overview/core-concepts/transaction-lifecycle.mdx	Adds 'Refund destination' subsection explaining per-funding-method refund behaviour; POST /transfer-out endpoint reference is valid and consistent with the rest of the codebase.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Transaction fails / is cancelled] --> B{How was it funded?}
    B -->|Prefunded internal account| C[Credit back to source\ninternal account balance]
    B -->|JIT via instant fiat rail\nRTP / PIX / SEPA Instant| D[Return to originating\nfunding instrument]
    B -->|JIT via crypto\nUSDC / BTC| E[Credit customer's internal\naccount balance for that asset]
    E --> F{Customer action}
    F -->|New quote| G[POST /quote → spend balance]
    F -->|Withdraw| H[POST /transfer-out]

Loading

_{Reviews (1): Last reviewed commit: "docs: document crypto refund destination..." | Re-trigger Greptile}