{
  "openapi": "3.0.3",
  "info": {
    "title": "AzPays API",
    "description": "Enterprise-grade Crypto Payment Orchestration Engine & Settlement Infrastructure.\nProvides multi-chain checkout, invoicing, recurring SaaS subscriptions, BIP-44/SLIP-0010 HD wallet derivation, Dual-Mother spending policies, OFAC compliance, and instant treasury settlements.",
    "version": "1.0.0",
    "contact": {
      "name": "AzPays Engineering",
      "url": "https://azpays.net",
      "email": "support@azpays.net"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://azpays.net/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.azpays.net",
      "description": "Production API Gateway"
    },
    {
      "url": "http://localhost:8000",
      "description": "Local Development Server"
    },
    {
      "url": "/",
      "description": "Current Environment / Relative Host"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Liveness and database readiness health probes"
    },
    {
      "name": "Checkout (Public)",
      "description": "Public hosted payment checkout portal, dynamic asset quoting, and address generation"
    },
    {
      "name": "Invoices",
      "description": "Enterprise invoicing with tax rates, line items, and crypto checkout links"
    },
    {
      "name": "Payments",
      "description": "Payment sessions, deposit tracking, tolerance confirmations, and manual adjustments"
    },
    {
      "name": "Payment Links",
      "description": "Reusable hosted payment links and paywalls"
    },
    {
      "name": "Donations",
      "description": "Crowdfunding campaigns, donor records, and public donation widgets"
    },
    {
      "name": "Subscriptions",
      "description": "Recurring billing plans, automated invoice scheduling, and subscriptions"
    },
    {
      "name": "Refunds",
      "description": "Overpayment/underpayment refunds, customer claims, and tolerance margins"
    },
    {
      "name": "Payouts",
      "description": "Merchant withdrawals, automated network fee estimation, and disbursals"
    },
    {
      "name": "Merchants",
      "description": "Merchant profiles, API key rotation, team members, and accepted crypto assets"
    },
    {
      "name": "User & Profile",
      "description": "User profile details, connected accounts, and dashboard metrics"
    },
    {
      "name": "Taxes",
      "description": "Jurisdictional VAT and sales tax rules with automated calculation"
    },
    {
      "name": "Discounts",
      "description": "Promo code management, percentage/fixed discounts, and checkout validation"
    },
    {
      "name": "Webhooks",
      "description": "Webhook endpoint configurations, event deliveries, and test dispatches"
    },
    {
      "name": "Wallets & HD Keys",
      "description": "BIP-44/SLIP-0010 multi-chain HD wallets, mnemonic seeds, transfers, and Dual-Mother spending policies"
    },
    {
      "name": "Transactions",
      "description": "On-chain blockchain transaction records and explorer links"
    },
    {
      "name": "Prices & Rates",
      "description": "Real-time fiat/crypto exchange rates and 24-hour historical candlestick feeds"
    },
    {
      "name": "Treasury & Vaults",
      "description": "Multi-asset vault accounting, rolling reserves, cashflow statements, and fee collectors"
    },
    {
      "name": "Telegram Ecosystem",
      "description": "Telegram Mini App (TMA) HMAC auth, deep-link challenge login, and bot webhooks"
    },
    {
      "name": "Search",
      "description": "Universal cross-entity search across invoices, payments, transactions, and customers"
    },
    {
      "name": "Audit Logs",
      "description": "Immutable security audit logs with before/after state diffs"
    },
    {
      "name": "Security & Compliance",
      "description": "Real-time OFAC / Sanctions crypto wallet screening"
    },
    {
      "name": "Integrations",
      "description": "Turnkey connectors for Discord, Slack, Zapier, and custom webhooks"
    },
    {
      "name": "Notifications",
      "description": "In-app notifications, preferences, and real-time SSE event streams"
    },
    {
      "name": "Platform Admin",
      "description": "System health, RPC node failover, chain configurations, and merchant governance"
    },
    {
      "name": "Legacy Gore Compatibility",
      "description": "Backward-compatible wallet and price endpoints"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Vyntech ID Bearer token or authenticated Telegram session JWT"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Merchant API Key (e.g. `az_live_...` or `az_test_...`). Automatically scopes all operations to the merchant associated with the API key, making `merchant_id` optional in request payloads and query filters."
      },
      "AdminAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Superadmin Bearer JWT with `azpays:owner` platform role"
      }
    },
    "schemas": {
      "BaseResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "msg": {
            "type": "string",
            "example": "Success"
          },
          "data": {
            "type": "object",
            "nullable": true
          }
        },
        "required": [
          "ok",
          "msg"
        ]
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "ok"
          },
          "database": {
            "type": "string",
            "example": "connected"
          },
          "version": {
            "type": "string",
            "example": "1.0.0-dev"
          }
        }
      },
      "CheckoutSession": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "token": {
            "type": "string",
            "example": "chk_live_8f3a9bc412"
          },
          "merchant_name": {
            "type": "string",
            "example": "Acme Corp"
          },
          "amount": {
            "type": "number",
            "example": 99.5
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "status": {
            "type": "integer",
            "description": "0: Registered, 1: Started, 2: Detected, 3: Verifying, 4: Confirmed, 5: Canceled, 6: Partial, 7: Paid Out",
            "example": 1
          },
          "status_text": {
            "type": "string",
            "example": "STARTED"
          },
          "description": {
            "type": "string",
            "example": "Pro Membership Plan"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CoinOption": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "name": {
            "type": "string",
            "example": "Tether USD (TRC20)"
          },
          "decimals": {
            "type": "integer",
            "example": 6
          },
          "contract_address": {
            "type": "string",
            "example": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
          },
          "icon_url": {
            "type": "string",
            "example": "https://assets.azpays.net/coins/usdt.svg"
          },
          "network_fee_est": {
            "type": "string",
            "example": "~$0.80"
          }
        }
      },
      "SelectCoinRequest": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          }
        },
        "required": [
          "chain",
          "symbol"
        ]
      },
      "SelectCoinResponse": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "format": "uuid"
          },
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "deposit_address": {
            "type": "string",
            "example": "TYDzsYUEpvnYmQk4zGP9sWWcTEd3JfW83z"
          },
          "amount_crypto": {
            "type": "string",
            "example": "99.500000"
          },
          "exchange_rate": {
            "type": "number",
            "example": 1.0
          },
          "rate_locked_until": {
            "type": "string",
            "format": "date-time"
          },
          "qr_code_url": {
            "type": "string",
            "example": "https://api.azpays.net/v1/checkout/chk_live_8f3a9bc412/qr"
          }
        }
      },
      "ApplyDiscountRequest": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "SUMMER2026"
          }
        },
        "required": [
          "code"
        ]
      },
      "CheckoutStatusResponse": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "example": "chk_live_8f3a9bc412"
          },
          "status": {
            "type": "integer",
            "example": 4
          },
          "status_text": {
            "type": "string",
            "example": "CONFIRMED"
          },
          "amount_expected": {
            "type": "string",
            "example": "99.500000"
          },
          "amount_received": {
            "type": "string",
            "example": "99.500000"
          },
          "confirmations": {
            "type": "integer",
            "example": 12
          },
          "required_confirmations": {
            "type": "integer",
            "example": 3
          },
          "tx_hash": {
            "type": "string",
            "example": "0x5c2a13f7098e94e2..."
          },
          "is_paid": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "InvoiceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "description": {
            "type": "string",
            "example": "Cloud API Subscription (Monthly)"
          },
          "quantity": {
            "type": "integer",
            "example": 1
          },
          "unit_price": {
            "type": "number",
            "example": 49.0
          },
          "amount": {
            "type": "number",
            "example": 49.0
          }
        },
        "required": [
          "description",
          "quantity",
          "unit_price"
        ]
      },
      "Invoice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "merchant_id": {
            "type": "string",
            "format": "uuid"
          },
          "invoice_number": {
            "type": "string",
            "example": "INV-2026-0042"
          },
          "customer_name": {
            "type": "string",
            "example": "John Doe"
          },
          "customer_email": {
            "type": "string",
            "format": "email",
            "example": "john@example.com"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "open",
              "paid",
              "void",
              "uncollectible"
            ],
            "example": "open"
          },
          "subtotal": {
            "type": "number",
            "example": 49.0
          },
          "tax_total": {
            "type": "number",
            "example": 4.9
          },
          "discount_total": {
            "type": "number",
            "example": 0.0
          },
          "total_amount": {
            "type": "number",
            "example": 53.9
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "public_token": {
            "type": "string",
            "example": "inv_pub_9a8b7c6d5e"
          },
          "payment_url": {
            "type": "string",
            "example": "http://localhost:8000/v1/invoices/public/inv_pub_9a8b7c6d5e"
          },
          "due_date": {
            "type": "string",
            "format": "date-time"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceItem"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateInvoiceRequest": {
        "type": "object",
        "properties": {
          "customer_name": {
            "type": "string",
            "example": "John Doe"
          },
          "customer_email": {
            "type": "string",
            "format": "email",
            "example": "john@example.com"
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "due_date": {
            "type": "string",
            "format": "date-time",
            "example": "2026-10-01T00:00:00Z"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InvoiceItem"
            }
          },
          "auto_finalize": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "customer_name",
          "customer_email",
          "items"
        ]
      },
      "Payment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "merchant_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "number",
            "example": 120.0
          },
          "status": {
            "type": "integer",
            "example": 4
          },
          "token": {
            "type": "string",
            "example": "pmt_4f5a6b7c8d"
          },
          "customer_id": {
            "type": "string",
            "example": "usr_991823"
          },
          "description": {
            "type": "string",
            "example": "Payment for Order #1002"
          },
          "accepted_chains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "trx",
              "ton"
            ]
          },
          "accepted_tokens": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "USDT",
              "TRX"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PaymentWallet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "payment_id": {
            "type": "string",
            "format": "uuid"
          },
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "address": {
            "type": "string",
            "example": "TYDzsYUEpvnYmQk4zGP9sWWcTEd3JfW83z"
          },
          "amount_expected": {
            "type": "string",
            "example": "120.000000"
          },
          "amount_received": {
            "type": "string",
            "example": "120.000000"
          },
          "tx_hash": {
            "type": "string",
            "example": "0x49f3e..."
          },
          "status": {
            "type": "integer",
            "example": 4
          }
        }
      },
      "PaymentLink": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "example": "vip-community-pass"
          },
          "title": {
            "type": "string",
            "example": "VIP Community Access"
          },
          "description": {
            "type": "string",
            "example": "Lifetime access to Telegram Alpha channel"
          },
          "amount": {
            "type": "number",
            "example": 50.0
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "is_reusable": {
            "type": "boolean",
            "example": true
          },
          "active": {
            "type": "boolean",
            "example": true
          },
          "redirect_url": {
            "type": "string",
            "example": "https://t.me/+AbCdEfGhIj"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DonationCampaign": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string",
            "example": "open-source-fund"
          },
          "title": {
            "type": "string",
            "example": "Open Source Fund 2026"
          },
          "description": {
            "type": "string",
            "example": "Supporting decentralized crypto infrastructure"
          },
          "target_amount": {
            "type": "number",
            "example": 10000.0
          },
          "raised_amount": {
            "type": "number",
            "example": 3450.0
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "donors_count": {
            "type": "integer",
            "example": 42
          },
          "active": {
            "type": "boolean",
            "example": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SubscriptionPlan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "SaaS Pro Tier"
          },
          "amount": {
            "type": "number",
            "example": 29.0
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "interval": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "yearly"
            ],
            "example": "monthly"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Subscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "plan_id": {
            "type": "string",
            "format": "uuid"
          },
          "customer_email": {
            "type": "string",
            "format": "email",
            "example": "alice@company.com"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "past_due",
              "canceled"
            ],
            "example": "active"
          },
          "current_period_start": {
            "type": "string",
            "format": "date-time"
          },
          "current_period_end": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Refund": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "payment_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount": {
            "type": "number",
            "example": 15.0
          },
          "reason": {
            "type": "string",
            "example": "Overpayment refund requested by customer"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "completed"
            ],
            "example": "pending"
          },
          "destination_address": {
            "type": "string",
            "example": "0x71C..."
          },
          "tx_hash": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ToleranceSetting": {
        "type": "object",
        "properties": {
          "underpayment_threshold_percent": {
            "type": "number",
            "example": 1.0
          },
          "underpayment_max_fiat": {
            "type": "number",
            "example": 1.0
          },
          "overpayment_action": {
            "type": "string",
            "enum": [
              "ignore",
              "refund",
              "credit"
            ],
            "example": "refund"
          }
        }
      },
      "Payout": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "payout_number": {
            "type": "string",
            "example": "PO-9941"
          },
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "amount": {
            "type": "number",
            "example": 500.0
          },
          "destination_address": {
            "type": "string",
            "example": "TYDzsYUEpvnYmQk4zGP9sWWcTEd3JfW83z"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "processing",
              "completed",
              "cancelled"
            ],
            "example": "completed"
          },
          "fee_estimated": {
            "type": "number",
            "example": 1.5
          },
          "tx_hash": {
            "type": "string",
            "example": "0x7a8b9c..."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "EstimateFeeResponse": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "estimated_fee": {
            "type": "number",
            "example": 1.2
          },
          "estimated_fee_crypto": {
            "type": "string",
            "example": "1.200000"
          },
          "fast_fee": {
            "type": "number",
            "example": 2.0
          }
        }
      },
      "Merchant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "Starlight Ventures"
          },
          "slug": {
            "type": "string",
            "example": "starlight-ventures"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "finance@starlight.io"
          },
          "api_key": {
            "type": "string",
            "example": "az_live_9f8e7d6c5b4a3"
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "example": "https://api.starlight.io/webhooks/azpays"
          },
          "webhook_secret": {
            "type": "string",
            "example": "whsec_38f72bc..."
          },
          "accepted_chains": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "trx",
              "eth",
              "bnb",
              "sol",
              "ton"
            ]
          },
          "accepted_tokens": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "USDT",
              "USDC"
            ]
          },
          "chain_confirmations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "chain": {
                  "type": "string",
                  "example": "trx"
                },
                "is_confirmations_required": {
                  "type": "boolean",
                  "example": false
                },
                "require_confirmations_count": {
                  "type": "integer",
                  "example": 19
                }
              }
            }
          },
          "token_confirmations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "symbol": {
                  "type": "string",
                  "example": "trx:TRX"
                },
                "is_confirmations_required": {
                  "type": "boolean",
                  "example": false
                },
                "require_confirmations_count": {
                  "type": "integer",
                  "example": 12
                }
              }
            }
          },
          "is_active": {
            "type": "boolean",
            "example": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "UserProfile": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "operator@vyntech.com"
          },
          "name": {
            "type": "string",
            "example": "Moezeh"
          },
          "role": {
            "type": "string",
            "example": "azpays:owner"
          },
          "telegram_id": {
            "type": "string",
            "nullable": true,
            "example": "123456789"
          },
          "telegram_username": {
            "type": "string",
            "nullable": true,
            "example": "moezeh"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SidebarCounts": {
        "type": "object",
        "properties": {
          "invoices": {
            "type": "string",
            "example": "14"
          },
          "payments": {
            "type": "string",
            "example": "1.2K"
          },
          "payouts": {
            "type": "string",
            "example": "3"
          },
          "wallets": {
            "type": "string",
            "example": "8"
          },
          "notifications": {
            "type": "string",
            "example": "2"
          }
        }
      },
      "TaxRate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "example": "Australian GST"
          },
          "percentage": {
            "type": "number",
            "example": 10.0
          },
          "jurisdiction": {
            "type": "string",
            "example": "AU"
          },
          "is_inclusive": {
            "type": "boolean",
            "example": false
          },
          "is_active": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "Discount": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "code": {
            "type": "string",
            "example": "PROMO20"
          },
          "type": {
            "type": "string",
            "enum": [
              "percent",
              "fixed"
            ],
            "example": "percent"
          },
          "value": {
            "type": "number",
            "example": 20.0
          },
          "max_redemptions": {
            "type": "integer",
            "nullable": true,
            "example": 100
          },
          "redemptions_count": {
            "type": "integer",
            "example": 14
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "event_type": {
            "type": "string",
            "example": "payment.confirmed"
          },
          "payload": {
            "type": "object"
          },
          "response_status": {
            "type": "integer",
            "example": 200
          },
          "response_body": {
            "type": "string",
            "example": "{\"status\":\"ok\"}"
          },
          "delivered_at": {
            "type": "string",
            "format": "date-time"
          },
          "attempts": {
            "type": "integer",
            "example": 1
          }
        }
      },
      "Wallet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "address": {
            "type": "string",
            "example": "TYDzsYUEpvnYmQk4zGP9sWWcTEd3JfW83z"
          },
          "account_index": {
            "type": "integer",
            "example": 0
          },
          "address_index": {
            "type": "integer",
            "example": 5
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "HDGenerateResponse": {
        "type": "object",
        "properties": {
          "seed_id": {
            "type": "string",
            "format": "uuid"
          },
          "mnemonic": {
            "type": "string",
            "example": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
          },
          "mother_wallets": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "trx": "TYDzsYUEpvnYmQk4zGP9sWWcTEd3JfW83z",
              "eth": "0x71C...b89",
              "sol": "7xKXtg...9",
              "ton": "EQBvW8...k1"
            }
          }
        }
      },
      "SpendingPolicy": {
        "type": "object",
        "properties": {
          "threshold_fiat": {
            "type": "number",
            "example": 100.0
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "require_dual_approval": {
            "type": "boolean",
            "example": true
          },
          "secondary_approver_email": {
            "type": "string",
            "example": "cfo@merchant.com"
          }
        }
      },
      "TransferRequest": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "recipient_address": {
            "type": "string",
            "example": "TJY7K9o..."
          },
          "amount": {
            "type": "number",
            "example": 75.0
          }
        },
        "required": [
          "chain",
          "symbol",
          "recipient_address",
          "amount"
        ]
      },
      "BlockchainTransaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "tx_hash": {
            "type": "string",
            "example": "0x3f5b8c..."
          },
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "from_address": {
            "type": "string",
            "example": "TYDzs..."
          },
          "to_address": {
            "type": "string",
            "example": "TJY7K..."
          },
          "amount": {
            "type": "number",
            "example": 99.5
          },
          "confirmations": {
            "type": "integer",
            "example": 25
          },
          "status": {
            "type": "string",
            "example": "confirmed"
          },
          "block_number": {
            "type": "integer",
            "example": 61298402
          },
          "explorer_url": {
            "type": "string",
            "example": "https://tronscan.org/#/transaction/0x3f5b8c..."
          },
          "detected_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PriceQuote": {
        "type": "object",
        "properties": {
          "symbol": {
            "type": "string",
            "example": "USDT"
          },
          "price_usd": {
            "type": "number",
            "example": 1.0002
          },
          "price_formatted": {
            "type": "string",
            "example": "$1.00"
          },
          "change_24h": {
            "type": "number",
            "example": 0.05
          },
          "volume_24h": {
            "type": "string",
            "example": "$54.2B"
          },
          "market_cap": {
            "type": "string",
            "example": "$118.4B"
          },
          "last_updated": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "TreasurySummary": {
        "type": "object",
        "properties": {
          "total_valuation_usd": {
            "type": "number",
            "example": 142500.5
          },
          "available_settlement_usd": {
            "type": "number",
            "example": 128250.0
          },
          "rolling_reserves_held_usd": {
            "type": "number",
            "example": 7125.0
          },
          "pending_payouts_usd": {
            "type": "number",
            "example": 7125.5
          },
          "assets_breakdown": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "chain": {
                  "type": "string",
                  "example": "trx"
                },
                "symbol": {
                  "type": "string",
                  "example": "USDT"
                },
                "balance": {
                  "type": "string",
                  "example": "45200.000000"
                },
                "valuation_usd": {
                  "type": "number",
                  "example": 45200.0
                }
              }
            }
          }
        }
      },
      "TelegramWebAppAuthRequest": {
        "type": "object",
        "properties": {
          "init_data": {
            "type": "string",
            "description": "Raw URL-encoded initData string provided by Telegram WebApp",
            "example": "query_id=AAHd...&user=%7B%22id%22%3A123%7D&hash=4f5..."
          }
        },
        "required": [
          "init_data"
        ]
      },
      "TelegramChallenge": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "example": "tgch_91f82a3c"
          },
          "deep_link": {
            "type": "string",
            "example": "https://t.me/AzPaysBot?start=auth_tgch_91f82a3c"
          },
          "expires_in_seconds": {
            "type": "integer",
            "example": 120
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "invoices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Invoice"
            }
          },
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payment"
            }
          },
          "transactions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BlockchainTransaction"
            }
          },
          "payouts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payout"
            }
          }
        }
      },
      "AuditLog": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "actor_id": {
            "type": "string",
            "example": "usr_991823"
          },
          "action": {
            "type": "string",
            "example": "payout.approved"
          },
          "resource_type": {
            "type": "string",
            "example": "payouts"
          },
          "resource_id": {
            "type": "string",
            "example": "PO-9941"
          },
          "ip_address": {
            "type": "string",
            "example": "192.168.1.100"
          },
          "old_state": {
            "type": "object",
            "nullable": true
          },
          "new_state": {
            "type": "object",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SanctionsScreenRequest": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "example": "eth"
          },
          "address": {
            "type": "string",
            "example": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a"
          }
        },
        "required": [
          "chain",
          "address"
        ]
      },
      "SanctionsScreenResult": {
        "type": "object",
        "properties": {
          "is_blocked": {
            "type": "boolean",
            "example": true
          },
          "reason": {
            "type": "string",
            "example": "OFAC SDN Listed Address (Tornado Cash Router)"
          },
          "category": {
            "type": "string",
            "example": "sanctioned_mixer"
          },
          "flagged_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Integration": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "provider": {
            "type": "string",
            "enum": [
              "discord",
              "slack",
              "zapier",
              "custom_webhook"
            ],
            "example": "discord"
          },
          "name": {
            "type": "string",
            "example": "Discord Sales Bot"
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "example": "https://discord.com/api/webhooks/..."
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "payment.confirmed",
              "invoice.paid"
            ]
          },
          "active": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "Notification": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "example": "Payment Received"
          },
          "message": {
            "type": "string",
            "example": "Customer John Doe paid $99.50 via USDT-TRC20"
          },
          "is_read": {
            "type": "boolean",
            "example": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ChainConfig": {
        "type": "object",
        "properties": {
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "name": {
            "type": "string",
            "example": "TRON Network"
          },
          "is_active": {
            "type": "boolean",
            "example": true
          },
          "required_confirmations": {
            "type": "integer",
            "example": 19
          },
          "active_nodes_count": {
            "type": "integer",
            "example": 3
          }
        }
      },
      "NodeConfig": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "chain": {
            "type": "string",
            "example": "trx"
          },
          "url": {
            "type": "string",
            "example": "https://api.trongrid.io"
          },
          "weight": {
            "type": "integer",
            "example": 10
          },
          "is_healthy": {
            "type": "boolean",
            "example": true
          },
          "latency_ms": {
            "type": "integer",
            "example": 85
          },
          "last_probed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PlatformOverview": {
        "type": "object",
        "properties": {
          "merchants_count": {
            "type": "integer",
            "example": 128
          },
          "total_volume_usd": {
            "type": "number",
            "example": 4589200.0
          },
          "total_tx_count": {
            "type": "integer",
            "example": 34910
          },
          "active_chains_count": {
            "type": "integer",
            "example": 6
          },
          "system_health": {
            "type": "string",
            "example": "operational"
          }
        }
      }
    }
  },
  "paths": {
    "/healthz": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Liveness Probe",
        "description": "Returns 200 OK as long as the API server process is alive.",
        "responses": {
          "200": {
            "description": "Process is healthy",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "ok"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Readiness Probe",
        "description": "Checks connectivity to PostgreSQL database pool and core services.",
        "responses": {
          "200": {
            "description": "Database and core services ready",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "ok"
                }
              }
            }
          },
          "503": {
            "description": "Database unreachable",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "unhealthy: database unreachable"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout/{token}": {
      "get": {
        "tags": [
          "Checkout (Public)"
        ],
        "summary": "Get Hosted Checkout Session",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Checkout session public token",
            "schema": {
              "type": "string",
              "example": "chk_live_8f3a9bc412"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "404 Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout/{token}/coins": {
      "get": {
        "tags": [
          "Checkout (Public)"
        ],
        "summary": "List Available Crypto Assets",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Checkout session public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CoinOption"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout/{token}/select-coin": {
      "post": {
        "tags": [
          "Checkout (Public)"
        ],
        "summary": "Select Crypto Asset & Lock Quote",
        "description": "Locks 30-minute exchange rate and dynamically assigns a multi-chain deposit address.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Checkout session public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SelectCoinRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SelectCoinResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "400 Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout/{token}/status": {
      "get": {
        "tags": [
          "Checkout (Public)"
        ],
        "summary": "Poll Checkout Payment Status",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Checkout session public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutStatusResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/checkout/{token}/discount": {
      "post": {
        "tags": [
          "Checkout (Public)"
        ],
        "summary": "Apply Promo Discount Code",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Checkout session public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplyDiscountRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "400 Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Checkout (Public)"
        ],
        "summary": "Remove Discount Code",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Checkout session public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices": {
      "get": {
        "tags": [
          "Invoices"
        ],
        "summary": "List Merchant Invoices",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number",
            "schema": {
              "type": "integer",
              "example": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Items per page",
            "schema": {
              "type": "integer",
              "example": 15
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status (draft, open, paid, void, uncollectible)",
            "schema": {
              "type": "string",
              "example": "open"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Invoice"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Create Draft or Finalized Invoice",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvoiceRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Invoice created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/stats": {
      "get": {
        "tags": [
          "Invoices"
        ],
        "summary": "Get Invoice Statistics",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_invoices": {
                          "type": "integer",
                          "example": 240
                        },
                        "paid_invoices": {
                          "type": "integer",
                          "example": 198
                        },
                        "total_revenue_usd": {
                          "type": "number",
                          "example": 54200.0
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}": {
      "get": {
        "tags": [
          "Invoices"
        ],
        "summary": "Get Invoice by ID",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string",
              "example": "8a9b0c1d-..."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "404 Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BaseResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Invoices"
        ],
        "summary": "Update Draft Invoice",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInvoiceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Invoices"
        ],
        "summary": "Delete Draft Invoice",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice deleted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}/finalize": {
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Finalize Invoice",
        "description": "Transitions invoice from 'draft' to 'open' and generates payment URL.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}/send": {
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Send Invoice to Customer",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice sent to customer",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}/void": {
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Void Open Invoice",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}/mark-uncollectible": {
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Mark Invoice Uncollectible",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/{id}/pay": {
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Initiate Crypto Payment for Invoice",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Invoice UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/public/{token}": {
      "get": {
        "tags": [
          "Invoices"
        ],
        "summary": "Public Invoice View",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Invoice public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Invoice"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/invoices/public/{token}/pay": {
      "post": {
        "tags": [
          "Invoices"
        ],
        "summary": "Customer Pay Public Invoice",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Invoice public token",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "List Payments",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number",
            "schema": {
              "type": "integer",
              "example": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Page size",
            "schema": {
              "type": "integer",
              "example": 15
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by state machine status",
            "schema": {
              "type": "integer",
              "example": 4
            }
          },
          {
            "name": "merchant_id",
            "in": "query",
            "required": false,
            "description": "Filter by merchant UUID. Optional when using ApiKeyAuth (defaults automatically to the merchant associated with the API key).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Create Payment Session",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "merchant_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Merchant UUID. Optional when using ApiKeyAuth (inferred automatically from X-API-Key). Required for multi-tenant Bearer JWT."
                  },
                  "fiat_amount": {
                    "type": "number",
                    "example": 100.0
                  },
                  "amount": {
                    "type": "number",
                    "example": 100.0
                  },
                  "description": {
                    "type": "string",
                    "example": "Custom Order #123"
                  },
                  "accepted_chains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "trx",
                      "ton"
                    ]
                  },
                  "accepted_tokens": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "USDT",
                      "TRX"
                    ]
                  }
                },
                "required": [
                  "fiat_amount"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/stats": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Payment Overview Metrics",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_volume": {
                          "type": "number",
                          "example": 125000.0
                        },
                        "total_count": {
                          "type": "integer",
                          "example": 890
                        },
                        "confirmed_count": {
                          "type": "integer",
                          "example": 845
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/reports": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Payment Settlement Reports",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payment"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Get Payment Details",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Payments"
        ],
        "summary": "Update Payment Metadata",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payment"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Payments"
        ],
        "summary": "Cancel / Delete Payment",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/wallets": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "List Assigned Payment Wallets",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PaymentWallet"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/wallet/generate": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Generate Child Wallet for Payment",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PaymentWallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/wallet/{address}": {
      "get": {
        "tags": [
          "Payments"
        ],
        "summary": "Inspect Wallet Status on Payment",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address",
            "in": "path",
            "required": true,
            "description": "Crypto address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PaymentWallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/wallet/{address}/watch": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Trigger Manual On-Chain Watch Probe",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address",
            "in": "path",
            "required": true,
            "description": "Crypto address",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Address queued for immediate watcher probe",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payments/{id}/process-payout": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Disburse / Payout Settled Payment",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payment UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment payout processed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment-links": {
      "get": {
        "tags": [
          "Payment Links"
        ],
        "summary": "List Payment Links",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PaymentLink"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Payment Links"
        ],
        "summary": "Create Payment Link",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "example": "Digital Art Print"
                  },
                  "amount": {
                    "type": "number",
                    "example": 25.0
                  },
                  "currency": {
                    "type": "string",
                    "example": "USD"
                  },
                  "description": {
                    "type": "string",
                    "example": "High resolution digital wallpaper"
                  }
                },
                "required": [
                  "title",
                  "amount",
                  "currency"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PaymentLink"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment-links/{id}": {
      "get": {
        "tags": [
          "Payment Links"
        ],
        "summary": "Get Payment Link",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Link UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PaymentLink"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Payment Links"
        ],
        "summary": "Update Payment Link",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Link UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentLink"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PaymentLink"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Payment Links"
        ],
        "summary": "Delete Payment Link",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Link UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment link deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment-links/public/{slug}": {
      "get": {
        "tags": [
          "Payment Links"
        ],
        "summary": "Public Payment Link Page",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Link slug",
            "schema": {
              "type": "string",
              "example": "vip-community-pass"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PaymentLink"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payment-links/public/{slug}/pay": {
      "post": {
        "tags": [
          "Payment Links"
        ],
        "summary": "Initiate Checkout from Public Link",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Link slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/campaigns": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "List Donation Campaigns",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DonationCampaign"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Donations"
        ],
        "summary": "Create Donation Campaign",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "example": "Open Source Fund"
                  },
                  "target_amount": {
                    "type": "number",
                    "example": 5000.0
                  },
                  "currency": {
                    "type": "string",
                    "example": "USD"
                  }
                },
                "required": [
                  "title",
                  "target_amount",
                  "currency"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DonationCampaign"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/stats": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Donations Aggregated Metrics",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_donated_usd": {
                          "type": "number",
                          "example": 18450.0
                        },
                        "total_donors": {
                          "type": "integer",
                          "example": 142
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/campaigns/{id}": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Get Campaign by ID",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Campaign UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DonationCampaign"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Donations"
        ],
        "summary": "Update Campaign",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Campaign UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DonationCampaign"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DonationCampaign"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Donations"
        ],
        "summary": "Delete Campaign",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Campaign UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/campaigns/{id}/donors": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "List Campaign Donors",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Campaign UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "donor_name": {
                            "type": "string",
                            "example": "Anonymous"
                          },
                          "amount": {
                            "type": "number",
                            "example": 50.0
                          },
                          "donated_at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/public/{slug}": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Public Donation Page",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Campaign slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/DonationCampaign"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/public/{slug}/donate": {
      "post": {
        "tags": [
          "Donations"
        ],
        "summary": "Submit Public Donation",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Campaign slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "donor_name": {
                    "type": "string",
                    "example": "Alice"
                  },
                  "amount": {
                    "type": "number",
                    "example": 25.0
                  },
                  "message": {
                    "type": "string",
                    "example": "Keep up the great work!"
                  }
                },
                "required": [
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/CheckoutSession"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/donations/public/{slug}/donors": {
      "get": {
        "tags": [
          "Donations"
        ],
        "summary": "Public List of Donors",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Campaign slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions/plans": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "List Subscription Plans",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SubscriptionPlan"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Create Subscription Plan",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionPlan"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SubscriptionPlan"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions/plans/{id}": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Get Subscription Plan",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Plan UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SubscriptionPlan"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Update Subscription Plan",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Plan UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscriptionPlan"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SubscriptionPlan"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Delete Subscription Plan",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Plan UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plan deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "List Active Subscriptions",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Subscription"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Subscribe Customer to Plan",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "customer_email": {
                    "type": "string",
                    "format": "email",
                    "example": "customer@example.com"
                  }
                },
                "required": [
                  "plan_id",
                  "customer_email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions/stats": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Subscription Metrics (MRR / Churn)",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "active_subscriptions": {
                          "type": "integer",
                          "example": 89
                        },
                        "mrr_usd": {
                          "type": "number",
                          "example": 4890.0
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions/{id}": {
      "get": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Get Subscription",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Subscription UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions/{id}/cancel": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Cancel Subscription",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Subscription UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/subscriptions/{id}/resume": {
      "post": {
        "tags": [
          "Subscriptions"
        ],
        "summary": "Resume Canceled Subscription",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Subscription UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Subscription"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/refunds": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "summary": "List Refunds",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Refund"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Refunds"
        ],
        "summary": "Create Refund Request",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "payment_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "amount": {
                    "type": "number",
                    "example": 20.0
                  },
                  "reason": {
                    "type": "string",
                    "example": "Overpayment adjustment"
                  }
                },
                "required": [
                  "payment_id",
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Refund"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/refunds/stats": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "summary": "Refund Overview Stats",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_refunded_usd": {
                          "type": "number",
                          "example": 1450.0
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/refunds/tolerance": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "summary": "Get Tolerance Margins",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ToleranceSetting"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Refunds"
        ],
        "summary": "Update Tolerance Margins",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ToleranceSetting"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/ToleranceSetting"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/refunds/{id}": {
      "get": {
        "tags": [
          "Refunds"
        ],
        "summary": "Get Refund",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Refund UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Refund"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/refunds/{id}/process": {
      "post": {
        "tags": [
          "Refunds"
        ],
        "summary": "Approve and Disburse Refund",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Refund UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Refund"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/refunds/public/claim": {
      "post": {
        "tags": [
          "Refunds"
        ],
        "summary": "Public Customer Refund Claim",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string",
                    "example": "chk_live_..."
                  },
                  "destination_address": {
                    "type": "string",
                    "example": "TYDzs..."
                  },
                  "reason": {
                    "type": "string",
                    "example": "Overpaid deposit"
                  }
                },
                "required": [
                  "token",
                  "destination_address"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Refund"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "List Payouts",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Payout"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Request Merchant Withdrawal Payout",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "USDT"
                  },
                  "destination_address": {
                    "type": "string",
                    "example": "TYDzs..."
                  },
                  "amount": {
                    "type": "number",
                    "example": 250.0
                  }
                },
                "required": [
                  "chain",
                  "symbol",
                  "destination_address",
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts/stats": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Payout Totals & Stats",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_paid_out_usd": {
                          "type": "number",
                          "example": 89200.0
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts/estimate-fee": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Estimate Blockchain Network Fee for Payout",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "USDT"
                  },
                  "amount": {
                    "type": "number",
                    "example": 100.0
                  }
                },
                "required": [
                  "chain",
                  "symbol",
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/EstimateFeeResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts/{id}": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get Payout Details",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payout UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts/{id}/approve": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Approve Pending Payout",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payout UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts/{id}/reject": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Reject Payout Request",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payout UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "example": "Compliance hold"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/payouts/{id}/cancel": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Cancel Pending Payout",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Payout UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Payout"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/assets": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "Get Supported Chains & Token Catalog",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/draft": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "Get Onboarding Draft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Save Onboarding Draft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Merchants"
        ],
        "summary": "Delete Draft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Draft deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "List User Merchants",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Merchant"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Create Merchant Profile",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Nexus Gaming"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "payments@nexus.gg"
                  }
                },
                "required": [
                  "name",
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Merchant"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/{id}": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "Get Merchant Profile",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Merchant"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Merchants"
        ],
        "summary": "Update Merchant Profile",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Merchant"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Merchant"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/{id}/api-key/rotate": {
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Regenerate Merchant API Key",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "api_key": {
                          "type": "string",
                          "example": "az_live_newkey_91823..."
                        },
                        "rotated_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/{id}/wallets": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "List Merchant Deposit Addresses",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Wallet"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/{id}/wallets/generate": {
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Generate Child Address for Merchant",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/merchants/{id}/users": {
      "get": {
        "tags": [
          "Merchants"
        ],
        "summary": "List Merchant Team Members",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Merchants"
        ],
        "summary": "Add Merchant Team Member",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Merchant UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "finance@merchant.com"
                  },
                  "role": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "viewer"
                    ],
                    "example": "admin"
                  }
                },
                "required": [
                  "email",
                  "role"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/user": {
      "get": {
        "tags": [
          "User & Profile"
        ],
        "summary": "Get Authenticated User Profile",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/UserProfile"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/user/sidebar-counts": {
      "get": {
        "tags": [
          "User & Profile"
        ],
        "summary": "Get Badge Counts for Navigation Sidebar",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SidebarCounts"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/user/connected-accounts": {
      "get": {
        "tags": [
          "User & Profile"
        ],
        "summary": "List Linked Identity Accounts (Telegram, Vyntech)",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/user/connect/telegram": {
      "post": {
        "tags": [
          "User & Profile"
        ],
        "summary": "Connect Telegram Account",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TelegramWebAppAuthRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Telegram account linked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "User & Profile"
        ],
        "summary": "Disconnect Telegram Account",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Telegram unlinked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/taxes": {
      "get": {
        "tags": [
          "Taxes"
        ],
        "summary": "List Configured Tax Rates",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TaxRate"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Taxes"
        ],
        "summary": "Create Jurisdictional Tax Rate",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaxRate"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TaxRate"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/taxes/calculate": {
      "post": {
        "tags": [
          "Taxes"
        ],
        "summary": "Calculate Tax for Order",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "amount": {
                    "type": "number",
                    "example": 100.0
                  },
                  "tax_rate_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "subtotal": {
                          "type": "number",
                          "example": 100.0
                        },
                        "tax_amount": {
                          "type": "number",
                          "example": 10.0
                        },
                        "total": {
                          "type": "number",
                          "example": 110.0
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/taxes/{id}": {
      "get": {
        "tags": [
          "Taxes"
        ],
        "summary": "Get Tax Rate",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tax UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TaxRate"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Taxes"
        ],
        "summary": "Update Tax Rate",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tax UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaxRate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TaxRate"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Taxes"
        ],
        "summary": "Delete Tax Rate",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Tax UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tax rate removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/discounts": {
      "get": {
        "tags": [
          "Discounts"
        ],
        "summary": "List Promo Codes",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Discount"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Discounts"
        ],
        "summary": "Create Promo Code",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Discount"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Discount"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/discounts/validate": {
      "post": {
        "tags": [
          "Discounts"
        ],
        "summary": "Validate Promo Code for Cart",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "example": "SAVE20"
                  },
                  "subtotal": {
                    "type": "number",
                    "example": 100.0
                  }
                },
                "required": [
                  "code",
                  "subtotal"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "is_valid": {
                          "type": "boolean",
                          "example": true
                        },
                        "discount_amount": {
                          "type": "number",
                          "example": 20.0
                        },
                        "final_amount": {
                          "type": "number",
                          "example": 80.0
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/discounts/{id}": {
      "get": {
        "tags": [
          "Discounts"
        ],
        "summary": "Get Promo Code Details",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Discount UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Discount"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Discounts"
        ],
        "summary": "Update Promo Code",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Discount UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Discount"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Discount"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Discounts"
        ],
        "summary": "Delete Promo Code",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Discount UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discount code deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "List Webhook Delivery Logs",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Inspect Webhook Delivery Log",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Delivery UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/WebhookDelivery"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/deliveries/{id}/resend": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Resend Webhook Event",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Delivery UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/WebhookDelivery"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/webhooks/test": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Send Test Ping Webhook",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "target_url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://webhook.site/my-id"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean"
                        },
                        "response_code": {
                          "type": "integer"
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets": {
      "get": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "List Registered Child Wallets",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Wallet"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Register External Wallet",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Wallet"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/chains": {
      "get": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Supported Derivation Chains",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/generate": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Generate Isolated Multi-Chain Keypair",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/import-private-key": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Import Raw Private Key with AES Envelope Encryption",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  },
                  "private_key": {
                    "type": "string",
                    "example": "3a107..."
                  },
                  "label": {
                    "type": "string",
                    "example": "Cold Sweep Hotkey"
                  }
                },
                "required": [
                  "chain",
                  "private_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/hd/generate": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Generate Master BIP-39 HD Seed",
        "description": "Generates 12 or 24 word mnemonic and multi-chain mother addresses (TRON, ETH, BSC, SOL, TON, BTC).",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "word_count": {
                    "type": "integer",
                    "enum": [
                      12,
                      24
                    ],
                    "default": 12,
                    "example": 12
                  },
                  "label": {
                    "type": "string",
                    "example": "Primary Mother Vault"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/HDGenerateResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/hd/import": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Import Existing BIP-39 Seed Phrase",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "mnemonic": {
                    "type": "string",
                    "example": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
                  },
                  "passphrase": {
                    "type": "string",
                    "default": "",
                    "example": ""
                  },
                  "label": {
                    "type": "string",
                    "example": "Secondary Approver Seed"
                  }
                },
                "required": [
                  "mnemonic"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/HDGenerateResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/hd/derive": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Derive Specific BIP-44 Child Address",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "seed_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  },
                  "account_index": {
                    "type": "integer",
                    "example": 0
                  },
                  "address_index": {
                    "type": "integer",
                    "example": 42
                  }
                },
                "required": [
                  "chain",
                  "account_index",
                  "address_index"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/seeds": {
      "get": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "List Master Seeds",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/seeds/{id}/confirm-backup": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Confirm Offline Seed Backup",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Seed UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Seed backup marked confirmed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/spending-policy": {
      "get": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Get Dual-Mother Spending Policy",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SpendingPolicy"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Configure Dual-Mother Spending Policy",
        "description": "Sets auto-signing threshold vs pending secondary approval threshold.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SpendingPolicy"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SpendingPolicy"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/transfer": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Initiate Wallet Transfer",
        "description": "Transfers below policy threshold are broadcast immediately. High-value transfers trigger secondary approval.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "tx_hash": {
                          "type": "string",
                          "example": "0x4b7e..."
                        },
                        "status": {
                          "type": "string",
                          "example": "broadcast"
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/transfers": {
      "get": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "List Wallet Transfers",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/transfers/{id}/approve": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Secondary Sign & Approve High-Value Transfer",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Transfer UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer authorized and broadcast on-chain",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/estimate-fee": {
      "post": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Estimate On-Chain Gas / Energy Fee",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  },
                  "symbol": {
                    "type": "string",
                    "example": "USDT"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/EstimateFeeResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/wallets/{id}/balance": {
      "get": {
        "tags": [
          "Wallets & HD Keys"
        ],
        "summary": "Query Live On-Chain Balance",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Wallet UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "native_balance": {
                          "type": "string",
                          "example": "142.500000"
                        },
                        "token_balances": {
                          "type": "object",
                          "additionalProperties": {
                            "type": "string"
                          },
                          "example": {
                            "USDT": "1250.000000"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/transactions": {
      "get": {
        "tags": [
          "Transactions"
        ],
        "summary": "List On-Chain Transactions",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number",
            "schema": {
              "type": "integer",
              "example": 1
            }
          },
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "description": "Filter by chain",
            "schema": {
              "type": "string",
              "example": "trx"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlockchainTransaction"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/transactions/stats": {
      "get": {
        "tags": [
          "Transactions"
        ],
        "summary": "Transaction Count & Volume Stats",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "total_count": {
                          "type": "integer",
                          "example": 1420
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/transactions/{id}": {
      "get": {
        "tags": [
          "Transactions"
        ],
        "summary": "Get Transaction Details",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Transaction UUID or TxHash",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/BlockchainTransaction"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/prices/{s}": {
      "get": {
        "tags": [
          "Prices & Rates"
        ],
        "summary": "Get Real-Time Price Quote",
        "parameters": [
          {
            "name": "s",
            "in": "path",
            "required": true,
            "description": "Crypto asset symbol (e.g. USDT, BTC, ETH, TRX, SOL, TON)",
            "schema": {
              "type": "string",
              "example": "USDT"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PriceQuote"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/prices/{s}/history": {
      "get": {
        "tags": [
          "Prices & Rates"
        ],
        "summary": "Get 24-Hour Price Candlestick History",
        "parameters": [
          {
            "name": "s",
            "in": "path",
            "required": true,
            "description": "Asset symbol",
            "schema": {
              "type": "string",
              "example": "BTC"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Universal Multi-Entity Search",
        "description": "Searches across invoices, payments, transactions, and addresses in a single call.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query term",
            "schema": {
              "type": "string",
              "example": "INV-2026-0042"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SearchResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit-logs": {
      "get": {
        "tags": [
          "Audit Logs"
        ],
        "summary": "List Platform Audit Logs",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": false,
            "description": "Filter by action (e.g. payout.approved)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resource_type",
            "in": "query",
            "required": false,
            "description": "Filter by entity",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditLog"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit-logs/{id}": {
      "get": {
        "tags": [
          "Audit Logs"
        ],
        "summary": "Get Audit Log with Before/After Diff",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Audit Log UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/AuditLog"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/treasury/summary": {
      "get": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "Merchant Treasury Valuation Summary",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TreasurySummary"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/treasury/balances": {
      "get": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "Multi-Asset Balance Breakdown",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/treasury/reserves": {
      "get": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "Rolling Reserves Status",
        "description": "Lists locked 5% reserves and their maturity release dates.",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/treasury/reports/cashflow": {
      "get": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "Monthly Inflow / Outflow Cashflow Report",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/treasury/admin/overview": {
      "get": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "Platform Master Treasury Overview",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/treasury/admin/fee-collectors": {
      "get": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "List Platform Fee Collectors",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Treasury & Vaults"
        ],
        "summary": "Configure Platform Fee Collector",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string"
                  },
                  "destination_address": {
                    "type": "string"
                  },
                  "fee_percent": {
                    "type": "number"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/telegram/webapp": {
      "post": {
        "tags": [
          "Telegram Ecosystem"
        ],
        "summary": "Authenticate Telegram Mini App (TMA)",
        "description": "Validates HMAC-SHA256 of Telegram WebApp initData against Bot Token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TelegramWebAppAuthRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "session_token": {
                          "type": "string",
                          "example": "tg_sess_eyJhbGciOi..."
                        },
                        "user": {
                          "$ref": "#/components/schemas/UserProfile"
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/telegram/challenge": {
      "post": {
        "tags": [
          "Telegram Ecosystem"
        ],
        "summary": "Generate QR / Deep-Link Login Challenge",
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/TelegramChallenge"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/telegram/challenge/status": {
      "get": {
        "tags": [
          "Telegram Ecosystem"
        ],
        "summary": "Poll Login Challenge Status",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "Challenge token",
            "schema": {
              "type": "string",
              "example": "tgch_91f82a3c"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "is_authenticated": {
                          "type": "boolean",
                          "example": true
                        },
                        "jwt_token": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/telegram/webhook": {
      "post": {
        "tags": [
          "Telegram Ecosystem"
        ],
        "summary": "Telegram Bot Inbound Webhook",
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/v1/admin/telegram/setwebhook": {
      "post": {
        "tags": [
          "Telegram Ecosystem"
        ],
        "summary": "Register Telegram Bot Webhook to Telegram Servers",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/security/screen": {
      "post": {
        "tags": [
          "Security & Compliance"
        ],
        "summary": "Real-time OFAC / Sanctions Address Screening",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SanctionsScreenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/SanctionsScreenResult"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/security/addresses": {
      "get": {
        "tags": [
          "Security & Compliance"
        ],
        "summary": "List Sanctioned Addresses Blacklist",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Security & Compliance"
        ],
        "summary": "Add Address to Sanctions Blacklist",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "eth"
                  },
                  "address": {
                    "type": "string",
                    "example": "0x..."
                  },
                  "reason": {
                    "type": "string",
                    "example": "Ransomware wallet"
                  }
                },
                "required": [
                  "chain",
                  "address",
                  "reason"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/integrations": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "List Connected Third-Party Integrations",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Integration"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Connect Discord / Slack / Zapier Integration",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Integration"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Integration"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/integrations/{id}/test": {
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Dispatch Test Notification Event",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Integration UUID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test event dispatched to provider",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/notifications": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "List User Notifications",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Notification"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/notifications/unread-count": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "Get Unread Count",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "unread_count": {
                          "type": "integer",
                          "example": 3
                        }
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/notifications/stream": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "Server-Sent Events (SSE) Live Stream",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "SSE event stream",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/notifications/mark-all-read": {
      "post": {
        "tags": [
          "Notifications"
        ],
        "summary": "Mark All Notifications as Read",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "All notifications marked read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/overview": {
      "get": {
        "tags": [
          "Platform Admin"
        ],
        "summary": "Platform Health & Global Metrics",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PlatformOverview"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/merchants": {
      "get": {
        "tags": [
          "Platform Admin"
        ],
        "summary": "List All Platform Merchants",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Merchant"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/infrastructure/chains": {
      "get": {
        "tags": [
          "Platform Admin"
        ],
        "summary": "List Configured Blockchains",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ChainConfig"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/infrastructure/nodes": {
      "get": {
        "tags": [
          "Platform Admin"
        ],
        "summary": "List Blockchain RPC Nodes & Failover State",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NodeConfig"
                      }
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/admin/infrastructure/nodes/probe-all": {
      "post": {
        "tags": [
          "Platform Admin"
        ],
        "summary": "Trigger Probe on All RPC Endpoints",
        "security": [
          {
            "AdminAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Probing active for all nodes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object",
                      "nullable": true
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/wallets/generate": {
      "post": {
        "tags": [
          "Legacy Gore Compatibility"
        ],
        "summary": "Legacy Wallet Generation",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "chain": {
                    "type": "string",
                    "example": "trx"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/wallets/summary": {
      "post": {
        "tags": [
          "Legacy Gore Compatibility"
        ],
        "summary": "Legacy Wallet Balance Summary",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/wallets/transfer": {
      "post": {
        "tags": [
          "Legacy Gore Compatibility"
        ],
        "summary": "Legacy Transfer Dispatch",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/wallets/estimate-fee": {
      "post": {
        "tags": [
          "Legacy Gore Compatibility"
        ],
        "summary": "Legacy Fee Estimation",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/EstimateFeeResponse"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/prices/{s}": {
      "get": {
        "tags": [
          "Legacy Gore Compatibility"
        ],
        "summary": "Legacy Price Query",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "s",
            "in": "path",
            "required": true,
            "description": "Symbol",
            "schema": {
              "type": "string",
              "example": "USDT"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "msg": {
                      "type": "string",
                      "example": "Operation completed successfully"
                    },
                    "data": {
                      "$ref": "#/components/schemas/PriceQuote"
                    }
                  },
                  "required": [
                    "ok",
                    "msg"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}