openapi: 3.1.0
info:
  title: Vexus Crypto Core API
  version: 1.0.0
  description: API custodial Vexus para BSC e TRON. Valores *_units são strings inteiras.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://api.vexuspay.fun/v1
    description: Produção
  - url: https://api-vexuscrypto.212-47-64-86.sslip.io/v1
    description: Domínio temporário de contingência
security:
  - VexusKey: []
    VexusSignature: []
tags:
  - name: Catalog
    description: Redes, ativos e pares habilitados pela Vexus.
  - name: Wallets
    description: Provisionamento e consulta de carteiras HD por rede.
  - name: Deposits
    description: Depósitos detectados, confirmações e crédito no ledger.
  - name: Withdrawals
    description: Cotação, autorização e acompanhamento de saques.
  - name: Swaps
    description: Cotação e execução de swaps BSC reconciliados.
  - name: Transfers
    description: Transferências internas liquidadas no ledger.
  - name: Admin
    description: Recursos operacionais restritos a credenciais administrativas.
paths:
  /networks:
    get: {operationId: listNetworks, tags: [Catalog], summary: Lista redes, responses: {'200': {$ref: '#/components/responses/Success'}, '401': {$ref: '#/components/responses/Error'}}}
  /assets:
    get:
      operationId: listAssets
      tags: [Catalog]
      summary: Lista ativos
      parameters: [{name: network, in: query, schema: {type: string, enum: [BSC, TRON]}}]
      responses: {'200': {$ref: '#/components/responses/Success'}, '401': {$ref: '#/components/responses/Error'}}
  /swap-pairs:
    get: {operationId: listSwapPairs, tags: [Catalog], summary: Lista pares BSC habilitados, responses: {'200': {$ref: '#/components/responses/Success'}, '401': {$ref: '#/components/responses/Error'}}}
  /wallets:
    post:
      operationId: createWallet
      tags: [Wallets]
      summary: Cria ou retorna carteira HD da rede
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateWallet'}}}}
      responses: {'201': {$ref: '#/components/responses/Success'}, '409': {$ref: '#/components/responses/Error'}, '422': {$ref: '#/components/responses/Error'}}
  /wallets/{id}:
    get:
      operationId: getWallet
      tags: [Wallets]
      summary: Consulta carteira
      parameters: [{$ref: '#/components/parameters/UuidPath'}]
      responses: {'200': {$ref: '#/components/responses/Success'}, '404': {$ref: '#/components/responses/Error'}}
  /wallets/{id}/balances:
    get:
      operationId: getWalletBalances
      tags: [Wallets]
      summary: Saldos ledger/on-chain separados
      parameters: [{$ref: '#/components/parameters/UuidPath'}]
      responses: {'200': {$ref: '#/components/responses/Success'}, '404': {$ref: '#/components/responses/Error'}}
  /wallets/{id}/transactions:
    get:
      operationId: listWalletTransactions
      tags: [Wallets]
      summary: Histórico da carteira
      parameters: [{$ref: '#/components/parameters/UuidPath'}, {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 100}}]
      responses: {'200': {$ref: '#/components/responses/Success'}, '404': {$ref: '#/components/responses/Error'}}
  /deposits:
    get:
      operationId: listDeposits
      tags: [Deposits]
      summary: Lista depósitos do tenant
      parameters: [{name: status, in: query, schema: {type: string}}, {name: external_user_id, in: query, schema: {type: string}}]
      responses: {'200': {$ref: '#/components/responses/Success'}, '401': {$ref: '#/components/responses/Error'}}
  /deposits/{id}:
    get: {operationId: getDeposit, tags: [Deposits], summary: Consulta depósito, parameters: [{$ref: '#/components/parameters/UuidPath'}], responses: {'200': {$ref: '#/components/responses/Success'}, '404': {$ref: '#/components/responses/Error'}}}
  /withdrawals/quote:
    post:
      operationId: quoteWithdrawal
      tags: [Withdrawals]
      summary: Calcula quote autoritativo de saque
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/WithdrawalQuoteRequest'}}}}
      responses: {'201': {$ref: '#/components/responses/Success'}, '422': {$ref: '#/components/responses/Error'}, '503': {$ref: '#/components/responses/Error'}}
  /withdrawals:
    post:
      operationId: createWithdrawal
      tags: [Withdrawals]
      summary: Autoriza e reserva um saque
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}, {$ref: '#/components/parameters/Pin'}, {$ref: '#/components/parameters/Otp'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ExecuteQuote'}}}}
      responses: {'201': {$ref: '#/components/responses/Success'}, '409': {$ref: '#/components/responses/Error'}}
  /withdrawals/{id}:
    get: {operationId: getWithdrawal, tags: [Withdrawals], summary: Consulta saque, parameters: [{$ref: '#/components/parameters/UuidPath'}], responses: {'200': {$ref: '#/components/responses/Success'}, '404': {$ref: '#/components/responses/Error'}}}
  /swaps/quote:
    post:
      operationId: quoteSwap
      tags: [Swaps]
      summary: Calcula rota e quote PancakeSwap BSC
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/SwapQuoteRequest'}}}}
      responses: {'201': {$ref: '#/components/responses/Success'}, '422': {$ref: '#/components/responses/Error'}}
  /swaps:
    post:
      operationId: createSwap
      tags: [Swaps]
      summary: Reserva e executa swap
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}, {$ref: '#/components/parameters/Pin'}, {$ref: '#/components/parameters/Otp'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ExecuteQuote'}}}}
      responses: {'201': {$ref: '#/components/responses/Success'}, '409': {$ref: '#/components/responses/Error'}}
  /swaps/{id}:
    get: {operationId: getSwap, tags: [Swaps], summary: Consulta swap e valores reais, parameters: [{$ref: '#/components/parameters/UuidPath'}], responses: {'200': {$ref: '#/components/responses/Success'}, '404': {$ref: '#/components/responses/Error'}}}
  /internal-transfers:
    post:
      operationId: createInternalTransfer
      tags: [Transfers]
      summary: Liquidação entre usuários no ledger
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/InternalTransfer'}}}}
      responses: {'201': {$ref: '#/components/responses/Success'}, '422': {$ref: '#/components/responses/Error'}}
  /admin/dashboard:
    get: {operationId: getAdminDashboard, tags: [Admin], summary: Indicadores operacionais, responses: {'200': {$ref: '#/components/responses/Success'}, '403': {$ref: '#/components/responses/Error'}}}
  /admin/{resource}:
    get:
      operationId: listAdminResource
      tags: [Admin]
      summary: Recursos operacionais allowlisted
      parameters: [{name: resource, in: path, required: true, schema: {type: string, enum: [networks, assets, rpcs, treasuries, fee-policies, reconciliations, audit, alerts, transactions, withdrawals, swaps, sweeps, webhooks, wallet-migrations, treasury-fundings]}}]
      responses: {'200': {$ref: '#/components/responses/Success'}, '403': {$ref: '#/components/responses/Error'}}
  /admin/controls:
    post:
      operationId: updateAdminControl
      tags: [Admin]
      summary: Atualiza kill switch/maintenance com auditoria
      parameters: [{$ref: '#/components/parameters/Pin'}, {$ref: '#/components/parameters/Otp'}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [control_key, enabled, reason], properties: {control_key: {type: string}, enabled: {type: boolean}, reason: {type: string}}}}}}
      responses: {'200': {$ref: '#/components/responses/Success'}, '403': {$ref: '#/components/responses/Error'}}
  /admin/reconcile:
    post:
      operationId: triggerReconciliation
      tags: [Admin]
      summary: Agenda reconciliação
      parameters: [{$ref: '#/components/parameters/Pin'}, {$ref: '#/components/parameters/Otp'}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [scope], properties: {scope: {type: string, enum: [LEDGER, TREASURY]}}}}}}
      responses: {'202': {$ref: '#/components/responses/Success'}, '403': {$ref: '#/components/responses/Error'}}
components:
  securitySchemes:
    VexusKey: {type: apiKey, in: header, name: X-Vexus-Key}
    VexusSignature: {type: apiKey, in: header, name: X-Vexus-Signature, description: HMAC-SHA256 da string canônica; requer também X-Vexus-Timestamp e X-Vexus-Nonce.}
  parameters:
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 8, maxLength: 128}}
    UuidPath: {name: id, in: path, required: true, schema: {type: string, format: uuid}}
    Pin: {name: X-Vexus-Pin, in: header, required: false, schema: {type: string}}
    Otp: {name: X-Vexus-OTP, in: header, required: false, schema: {type: string}}
  schemas:
    Units: {type: string, pattern: '^[0-9]+$', example: '1000000'}
    CreateWallet:
      type: object
      additionalProperties: false
      required: [external_user_id, network]
      properties: {external_user_id: {type: string, maxLength: 160}, network: {type: string, enum: [BSC, TRON]}}
      examples: [{external_user_id: customer_123, network: BSC}]
    WithdrawalQuoteRequest:
      type: object
      additionalProperties: false
      required: [external_user_id, network, asset, destination_address, amount_units]
      properties: {external_user_id: {type: string}, network: {type: string, enum: [BSC, TRON]}, asset: {type: string}, destination_address: {type: string}, amount_units: {$ref: '#/components/schemas/Units'}}
      examples: [{external_user_id: customer_123, network: BSC, asset: USDT_BSC, destination_address: '0x1111111111111111111111111111111111111111', amount_units: '1000000'}]
    SwapQuoteRequest:
      type: object
      additionalProperties: false
      required: [external_user_id, asset_in, asset_out, amount_in_units]
      properties: {external_user_id: {type: string}, asset_in: {type: string}, asset_out: {type: string}, amount_in_units: {$ref: '#/components/schemas/Units'}, slippage_bps: {type: integer, minimum: 1, maximum: 10000}}
      examples: [{external_user_id: customer_123, asset_in: BNB, asset_out: USDT_BSC, amount_in_units: '10000000000000000', slippage_bps: 50}]
    ExecuteQuote: {type: object, additionalProperties: false, required: [quote_id], properties: {quote_id: {type: string, format: uuid}}}
    InternalTransfer:
      type: object
      additionalProperties: false
      required: [sender_external_user_id, recipient_external_user_id, asset, network, amount_units]
      properties: {sender_external_user_id: {type: string}, recipient_external_user_id: {type: string}, asset: {type: string}, network: {type: string}, amount_units: {$ref: '#/components/schemas/Units'}}
      examples: [{sender_external_user_id: customer_123, recipient_external_user_id: customer_456, asset: USDT_BSC, network: BSC, amount_units: '1000000'}]
    Error:
      type: object
      required: [code, message, trace_id]
      properties: {code: {type: string}, message: {type: string}, trace_id: {type: string, format: uuid}}
      examples: [{code: INSUFFICIENT_BALANCE, message: Saldo insuficiente para realizar a operação., trace_id: 018f5ee8-b289-7b8a-9b35-5e913a1b2300}]
    WebhookEvent:
      type: object
      additionalProperties: false
      required: [id, event_type, created_at, data]
      properties:
        id: {type: string, format: uuid}
        event_type: {type: string, enum: [wallet.created, deposit.detected, deposit.confirmed, deposit.credited, withdrawal.created, withdrawal.broadcasted, withdrawal.confirmed, withdrawal.failed, swap.created, swap.confirmed, swap.failed, balance.updated, webhook.test]}
        created_at: {type: string, format: date-time}
        data: {type: object, additionalProperties: true}
  responses:
    Success:
      description: Operação aceita
      headers:
        X-Trace-Id: {schema: {type: string, format: uuid}, description: Correlação sanitizada da requisição.}
        X-RateLimit-Limit: {schema: {type: integer}, description: Limite da credencial na janela.}
        X-RateLimit-Remaining: {schema: {type: integer}, description: Requisições restantes na janela.}
      content: {application/json: {schema: {type: object}}}
    Error:
      description: Erro sanitizado
      headers:
        X-Trace-Id: {schema: {type: string, format: uuid}, description: Correlação sanitizada da requisição.}
        Retry-After: {schema: {type: integer}, description: Segundos para nova tentativa quando aplicável.}
      content: {application/json: {schema: {$ref: '#/components/schemas/Error'}}}
webhooks:
  vexusEvent:
    post:
      operationId: receiveVexusWebhook
      summary: Evento assinado enviado ao endpoint do parceiro
      description: Valide X-Vexus-Signature sobre timestamp.event_id.raw_body antes de responder 2xx.
      parameters:
        - {name: X-Vexus-Event-Id, in: header, required: true, schema: {type: string, format: uuid}}
        - {name: X-Vexus-Timestamp, in: header, required: true, schema: {type: string, pattern: '^[0-9]{10}$'}}
        - {name: X-Vexus-Signature, in: header, required: true, schema: {type: string, pattern: '^sha256=[a-f0-9]{64}$'}}
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/WebhookEvent'}}}}
      responses: {'204': {description: Evento aceito}, '401': {description: Assinatura rejeitada}}