{
  "openapi": "3.0.0",
  "info": {
    "title": "Solana Deposit Addresses API",
    "version": "1.0.0",
    "description": "REST API for generating Solana deposit addresses (a deterministic EVM address on Base that auto-bridges USDC to a Solana wallet) and querying their records."
  },
  "servers": [
    { "url": "https://deposit-addresses.eco.com", "description": "Mainnet" }
  ],
  "tags": [
    { "name": "Deposit Addresses" }
  ],
  "paths": {
    "/api/v1/depositAddresses/solana": {
      "post": {
        "tags": ["Deposit Addresses"],
        "summary": "Generate Solana deposit address",
        "operationId": "generateSolanaDepositAddress",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSolanaDepositAddressDTO" } } }
        },
        "responses": {
          "201": {
            "description": "Deposit address (deterministic: same inputs always return the same address)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddressResponse" } } }
          },
          "400": {
            "description": "Validation failure or unconfigured chain",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    },
    "/api/v1/depositAddresses/evmAddress/{evmAddress}": {
      "get": {
        "tags": ["Deposit Addresses"],
        "summary": "Get deposit address record",
        "operationId": "getDepositAddress",
        "parameters": [
          { "name": "evmAddress", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EvmAddress" } }
        ],
        "responses": {
          "200": {
            "description": "Deposit address record",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddressResponse" } } }
          },
          "400": {
            "description": "Deposit address not found (errorDesc: NoSuchDepositAddress)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "EvmAddress": {
        "type": "string",
        "pattern": "^0x[a-fA-F0-9]{40}$",
        "description": "EIP-55 / lowercase hex 20-byte address",
        "example": "0x000000000000000000000000000000000000dEaD"
      },
      "SolanaAddress": {
        "type": "string",
        "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$",
        "description": "base58, 32-44 chars",
        "example": "2ECrxAiyVBszAjok5isDdTJu4kwwhq9d7kgJqDvEStMq"
      },
      "CreateSolanaDepositAddressDTO": {
        "type": "object",
        "required": ["chainId", "solanaAddress", "depositor"],
        "properties": {
          "chainId": { "type": "integer", "minimum": 1, "description": "Source chain. Currently Base (8453)." },
          "solanaAddress": { "$ref": "#/components/schemas/SolanaAddress" },
          "depositor": { "$ref": "#/components/schemas/EvmAddress", "description": "Authorized for refunds if the intent expires" }
        }
      },
      "DepositAddress": {
        "type": "object",
        "properties": {
          "addressID": { "type": "string", "format": "uuid", "description": "Internal record ID" },
          "depositAddressType": { "type": "string", "enum": ["SOLANA"], "description": "Deposit address product type" },
          "chainId": { "type": "integer" },
          "evmDepositAddress": { "$ref": "#/components/schemas/EvmAddress" },
          "solanaAddress": { "type": "string", "description": "Hex-encoded 32-byte Solana public key (the base58 address you submitted, decoded)" },
          "depositor": { "$ref": "#/components/schemas/EvmAddress" },
          "factoryAddress": { "$ref": "#/components/schemas/EvmAddress" },
          "isDeployed": { "type": "boolean" },
          "lastCheckedBalance": { "type": "string", "description": "Raw token units" },
          "lastBalanceCheckAt": { "type": "string", "format": "date-time", "description": "Unix epoch until the first balance check runs" },
          "lastBlockNumber": { "type": "string", "description": "Last block scanned by balance monitoring" },
          "deploymentTxHash": { "type": "string", "nullable": true },
          "deploymentBlockNumber": { "type": "string", "nullable": true },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "DepositAddressResponse": {
        "type": "object",
        "properties": { "data": { "$ref": "#/components/schemas/DepositAddress" } }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "statusCode": { "type": "integer", "example": 400 },
          "createdBy": { "type": "string", "description": "ValidationFilter for input validation failures, HttpExceptionFilter for business errors" },
          "validationErrors": {
            "type": "object",
            "additionalProperties": { "type": "string" },
            "description": "Field-to-message map. Present on validation failures."
          },
          "details": {
            "type": "object",
            "description": "Present on business errors",
            "properties": {
              "errorCode": { "type": "integer", "example": 1014 },
              "errorDesc": { "type": "string", "example": "NoSuchDepositAddress" },
              "cause": { "type": "string", "example": "NoSuchDepositAddress" }
            }
          }
        }
      }
    }
  }
}