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

# Security & Architecture

> Non-custodial design, on-chain verification, and security guarantees

# Security & Architecture

Stable Genius is built with a non-custodial, on-chain-first architecture. This page explains the security guarantees, trust model, and how you can independently verify every transaction.

## Non-Custodial Design

Stable Genius never holds merchant funds. Every merchant has a dedicated smart contract (GenieIntake proxy) deployed on Base that they control.

```mermaid theme={null}
flowchart TD
    Wallet["Customer's Wallet"]
    Wallet -- "Sends USDC" --> Proxy

    subgraph Contract["Merchant's GenieIntake Proxy Contract"]
        Proxy["Receives USDC"]
        Proxy --> Fees["Splits fees on-chain"]
        Fees --> Settle["Settles to merchant wallet"]
        Settle --> Emergency["emergencyWithdraw available"]
    end
```

### What This Means

**For merchants:** Your funds sit in a smart contract you control. Even if Stable Genius goes offline, you can call `emergencyWithdraw()` directly on your contract to retrieve all funds to your own wallet. No one — not Stable Genius, not an attacker — can redirect your funds to a different address.

**For integrators:** You never touch USDC. Your system creates payment intents and receives webhooks. All fund movement happens on-chain between the customer's wallet and the merchant's contract.

**For compliance:** Every transaction is recorded on-chain with full traceability. Transaction hash, sender, receiver, amount, block number — all publicly verifiable on [Basescan](https://basescan.org).

## Trust Model

| Role                         | What It Can Do                                                           | What It Cannot Do                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Merchant**                 | Withdraw funds to their own wallet at any time via `emergencyWithdraw()` | N/A — full control of their contract                                                                            |
| **Operator** (Stable Genius) | Call `settle()` to split fees and move net amount to merchant wallet     | Redirect funds to a different address, change fee rate without merchant consent, access merchant's private keys |
| **Integrator**               | Create payment intents, read transaction data                            | Access merchant funds, modify settlement configuration                                                          |
| **Customer**                 | Send USDC to payment addresses                                           | Reverse a confirmed payment (blockchain finality)                                                               |

## On-Chain Verification

Every payment processed through Stable Genius can be independently verified:

1. **Transaction hash** — Returned in the webhook and GET responses. Look it up on [Basescan](https://basescan.org) to see the exact USDC transfer.
2. **Fee split** — The `settle()` transaction on-chain shows the fee amount sent to the treasury and the net amount sent to the merchant.
3. **Contract code** — GenieIntake proxy contracts are verified on Basescan. Anyone can read the contract logic and confirm the fee split mechanics.

```bash theme={null}
# Example: Verify a payment on Basescan
https://basescan.org/tx/{tx_hash}
```

## Data Security

| Data                    | Protection                                                                                                              |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| API keys                | SHA-256 hashed at rest. Only shown once at creation.                                                                    |
| Webhook signing secrets | Unique per endpoint. HMAC-SHA256 verification.                                                                          |
| Merchant PII (KYC data) | Held by our identity verification partner, not by Stable Genius. We store only the verification status and customer ID. |
| Bank account details    | Connected via Plaid (tokenized). We store only bank name and last 4 digits.                                             |
| Transaction data        | Stored with row-level security. Each merchant can only access their own data.                                           |

## Infrastructure

| Component             | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| API & Dashboard       | Edge-deployed, auto-scaling, globally distributed.                       |
| Database              | Row-level security ensures each merchant can only access their own data. |
| Blockchain monitoring | Webhook-based real-time transaction detection on Base.                   |
| Identity verification | KYC/KYB via Bridge (a Stripe company).                                   |
| Bank linking          | Instant bank account verification via Plaid.                             |
| Smart contracts       | GenieIntake proxy contracts on Base (Ethereum L2).                       |

## Compliance

Stable Genius is designed for US regulatory compliance:

* **KYC/KYB** is required for all merchants before they can accept payments
* **Non-custodial architecture** means we don't fall under money transmitter licensing requirements for fund custody
* **On-chain audit trail** provides full transaction traceability for any regulatory inquiry
* **Bank-grade off-ramping** via Bridge (a Stripe company) for USDC-to-USD conversion

<Note>
  This is not legal advice. Consult with your legal team regarding compliance requirements for your specific use case and jurisdiction.
</Note>

## Reporting Vulnerabilities

If you discover a security vulnerability, please report it responsibly to **[security@stablegenius.co](mailto:security@stablegenius.co)**. Do not disclose vulnerabilities publicly before we've had a chance to address them. We aim to acknowledge reports within 24 hours and provide a resolution timeline within 72 hours.