{
  "openapi": "3.0.3",
  "info": {
    "title": "Digamber Vault Developer API",
    "description": "Production REST API for Digamber Vault multi-chain USDT custody, automated deposit & payment verification, balances, and on-chain settlements across BNB Smart Chain (BEP-20), TRON (TRC-20), and Ethereum (ERC-20).",
    "version": "1.4.0",
    "contact": {
      "name": "Digamber Vault Support",
      "url": "https://www.digamber.in/faq"
    }
  },
  "servers": [
    {
      "url": "https://api.digamber.in/v1",
      "description": "Primary Production API"
    },
    {
      "url": "https://www.digamber.in/v1",
      "description": "Mirrored Production API"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API_KEY",
        "description": "Secret API Key provisioned in the Developer Console, formatted as `dg_live_...`."
      },
      "HmacAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "HMAC authentication using X-API-KEY, X-TIMESTAMP, and X-SIGNATURE (HMAC-SHA256 hex)."
      }
    },
    "schemas": {
      "DepositRecord": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "e4b52c01-7fa1-4a11-82d9-1123456789ab" },
          "chain": { "type": "string", "enum": ["BSC", "TRON", "ETH"], "example": "BSC" },
          "network": { "type": "string", "example": "BEP20" },
          "token": { "type": "string", "example": "USDT" },
          "amount": { "type": "string", "example": "100.000000" },
          "status": { "type": "string", "enum": ["PENDING", "CONFIRMED", "SWEPT"], "example": "CONFIRMED" },
          "txHash": { "type": "string", "example": "0x7b2f4c5e3d1a890123456789abcdef0123456789abcdef0123456789abcdef01" },
          "fromAddress": { "type": "string", "example": "0x1234567890123456789012345678901234567890" },
          "depositAddress": { "type": "string", "example": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" },
          "blockNumber": { "type": "integer", "example": 38459201 },
          "createdAt": { "type": "string", "format": "date-time", "example": "2026-10-06T00:00:00.000Z" }
        }
      },
      "ApiResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "object" },
          "message": { "type": "string" }
        }
      }
    }
  },
  "security": [
    { "BearerAuth": [] }
  ],
  "paths": {
    "/deposits/{id}": {
      "get": {
        "summary": "Verify Deposit / Payment by ID or Blockchain Transaction Hash",
        "description": "Primary payment verification endpoint. Accepts either internal deposit UUID or the on-chain blockchain Transaction Hash (txHash) on BSC, TRON, or Ethereum.",
        "operationId": "verifyDepositByIdOrTxHash",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Internal deposit UUID or on-chain transaction hash (e.g. 0x... or 64-char Tron tx hash)",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Deposit found and verified successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "data": { "$ref": "#/components/schemas/DepositRecord" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Deposit or transaction hash not found"
          }
        }
      }
    },
    "/deposits": {
      "get": {
        "summary": "List Verified Deposits",
        "description": "Returns a paginated list of incoming deposits with optional blockchain filter.",
        "operationId": "listDeposits",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "required": false,
            "description": "Filter by chain: bsc, tron, or eth",
            "schema": { "type": "string", "enum": ["bsc", "tron", "eth"] }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of deposits"
          }
        }
      }
    },
    "/balances": {
      "get": {
        "summary": "Get Multi-Chain Balances",
        "description": "Returns isolated available and locked balances across BNB Smart Chain, TRON, and Ethereum.",
        "operationId": "getBalances",
        "responses": {
          "200": {
            "description": "Segregated balance information"
          }
        }
      }
    },
    "/wallets": {
      "get": {
        "summary": "Get Deposit Addresses",
        "description": "Returns user-specific HD deposit addresses for BSC, TRON, and Ethereum.",
        "operationId": "getWallets",
        "responses": {
          "200": {
            "description": "Deposit addresses by chain"
          }
        }
      }
    },
    "/account": {
      "get": {
        "summary": "Get Account Profile",
        "description": "Returns authenticated user profile and API key permission mode (READ_ONLY or READ_AND_TRANSACT).",
        "operationId": "getAccount",
        "responses": {
          "200": {
            "description": "Account details"
          }
        }
      }
    },
    "/withdrawals/estimate-fee": {
      "get": {
        "summary": "Estimate Withdrawal Network Fee",
        "description": "Calculates live dynamic gas/energy cost for the requested chain and net amount recipient receives.",
        "operationId": "estimateWithdrawalFee",
        "parameters": [
          {
            "name": "chain",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "enum": ["bsc", "tron", "eth"] }
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "schema": { "type": "number" }
          }
        ],
        "responses": {
          "200": {
            "description": "Fee estimate"
          }
        }
      }
    },
    "/withdrawals": {
      "post": {
        "summary": "Initiate External Withdrawal",
        "description": "Executes on-chain USDT transfer. Requires READ_AND_TRANSACT permission.",
        "operationId": "createWithdrawal",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Unique UUID for idempotency protection",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["chain", "toAddress", "amount"],
                "properties": {
                  "chain": { "type": "string", "enum": ["bsc", "tron", "eth"] },
                  "toAddress": { "type": "string" },
                  "amount": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Withdrawal created and queued for broadcast"
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "API Service Health",
        "security": [],
        "responses": {
          "200": {
            "description": "API status ok"
          }
        }
      }
    }
  }
}