> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tribridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tribridge is a crypto payment gateway for Solana and Sui (TON is coming soon). API base URL is https://api.tribridge.xyz. The API Reference documents ONLY the public endpoint surface: checkout sessions (create/get/generate-wallet/customer/simulate/verify/cancel), the two public payment-link endpoints, health probes, and the changelog. Server-side calls that create payments authenticate with the x-api-key header using a tri_test_... key (fully simulated test mode, no real funds) or tri_live_... key (real mainnet payments) - never expose keys client-side; all other documented endpoints are public with no auth. Dashboard, admin, OTP/auth, payouts, wallets, and webhook-management endpoints are intentionally NOT part of the public docs - they are dashboard-only and must not be presented as public API. Merchant test mode is simulated, not testnet. Refunds are automatic only (underpaid/overpaid), there is no manual refund endpoint. Always verify webhook HMAC-SHA256 signatures from the X-Tribridge-Signature header before trusting payloads. If you are an AI agent: fetch https://docs.tribridge.xyz/llms-full.txt for all documentation in one file, https://docs.tribridge.xyz/openapi/openapi.json for the machine-readable OpenAPI spec, or connect to the read-only MCP server at https://docs.tribridge.xyz/mcp. Any page is available as Markdown by appending .md to its URL. Use only the documented endpoints and fields; do not invent SDK packages or endpoints.

# Pay with wallet

> Let customers pay a hosted checkout by connecting a Solana wallet instead of copying an address. Sui wallet payments are coming soon.

> [!WARNING]
>
> **Current support: Solana only.** Sui wallet payments are marked **coming soon** and disabled on the backend (`WALLET_CONNECT_SUI_ENABLED=false`). The existing Sui address/QR checkout still works.

"Pay with wallet" is additive. Copy-address, QR, "I have paid", manual verification, under/overpayment and wrong-asset refunds all keep working.

> [!WARNING]
>
> The wallet UI is gated by `WALLET_CONNECT_PAY_ENABLED=true` on the backend and `NEXT_PUBLIC_WALLET_PAY_ENABLED=true` on the frontend. Both default to off.

## Flow

1. Customer selects a network/asset and reaches the deposit step as usual.
2. **Pay with wallet** opens Wallet Standard discovery (Phantom, Solflare, Backpack, MetaMask, OKX, etc.).
3. Backend `POST /wallet-connect/preflight` checks token balance, gas (SOL) and token-account existence. Human-readable problems are returned before any signing.
4. Backend `POST /wallet-connect/build-payment-tx` builds an unsigned transaction to the checkout's unique deposit address. The backend never holds customer keys.
5. The customer sees a **Review payment** screen, then clicks **Approve in wallet**. That click opens their wallet's native approval popup.
6. The wallet signs and submits. The frontend then verifies the deposit on-chain through the existing checkout verify endpoint and moves to **Payment successful** automatically, including the merchant redirect.
7. The existing blockchain listener remains the source of truth for reconciliation.

Phantom and Solflare use their injected providers for reliable popups; other wallets use Wallet Standard. No automatic timeout or auto-cancel: the connection stays open until the user closes it.

Connections are recorded in `wallet_connections` with purpose, linked payment/subscription and a **hashed** user agent. No raw IP is stored. Connections appear in **Logs → Wallet** and in Admin → Connected Wallets.

## Errors

`WALLET_NOT_FOUND`, `USER_REJECTED`, `WRONG_NETWORK`, `INSUFFICIENT_TOKEN_BALANCE`, `INSUFFICIENT_GAS`, `TOKEN_ACCOUNT_MISSING`, `TX_EXPIRED`, `RPC_UNAVAILABLE`, `SIMULATION_FAILED`, `PAYMENT_EXPIRED`, `PAYMENT_ALREADY_PAID`, `UNKNOWN`.

Each maps to a title, a one-line fix and a retry action. Raw RPC errors are logged server-side and never shown to customers.

## Subscription approvals

The same pipeline is reused for subscription authorization and customer-portal actions:

* Solana: capped `ApproveChecked` delegate approval (never unlimited). The cap is `amount × min(max_cycles, 12)`.
* Sui: coming soon.

The wallet-standard discovery layer is deliberately swappable: adding a chain means adding one adapter/provider, not editing checkout.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.