> ## 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://tribridge.onrender.com. Server-side calls 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. 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.

# Errors

> HTTP status codes, amount-mismatch events, and how to build a resilient integration.

## Standard errors

Tribridge uses standard HTTP response codes. The most common ones:

| Code | Title | What it means | What to do |
| - | - | - | - |
| `400` | Bad Request | Missing/invalid parameter (e.g. no `amount`, bad `currency`). | Validate required fields and types before sending. |
| `401` | Unauthorized | No valid API key provided. | Check the `x-api-key` header, key mode (test vs live), and that the keypair wasn't revoked. |
| `404` | Not Found | The resource (payment, payout, webhook) doesn't exist. | Check the ID; test-mode IDs don't exist in live mode and vice versa. |
| `429` | Too Many Requests | Rate limit hit — 100 requests/minute per IP. | Slow down with exponential backoff. |
| `500` | Server Error | Something went wrong on our side; the request was not processed. | Retry with backoff. If it persists, contact support with the payment ID and timestamp. |

## Payment-level failures (not HTTP errors)

These arrive as **webhook events**, not error codes — your handler must expect them:

* **Underpaid / overpaid** — the customer sent the wrong amount. Tribridge emits `payment.underpaid` / `payment.overpaid` and refunds automatically (see [Refunds](/refunds)). Never assume received equals invoiced; never fulfill on a mismatch.
* **Expired** — `payment.expired` means nothing arrived before `expires_at`. Release held stock and let the customer start a fresh payment.
* **Signature mismatch** — your webhook verification rejected a payload. Return non-2xx so Tribridge retries; then check you're hashing the raw body with the correct endpoint secret.

<Warning>
  Fulfillment rule of thumb: fulfill orders **only** on verified `payment.completed` events. Redirects can be faked and `payment.confirmed` precedes the final sweep — `completed` is the terminal success state your business logic should key on.
</Warning>


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