openapi: 3.1.0
info:
  title: bitsARK Exchanges API
  description: |
    API pública com dados fiscais e regulatórios de corretoras de cripto no Brasil.

    ## Autenticação

    A maioria dos endpoints é pública e não requer autenticação. O endpoint interno
    `/exchanges/dolarmap` requer o header `X-Internal-Token`.

    ## Rate Limiting

    **60 requisições por minuto** por IP. Requisições excedentes retornam HTTP 429.
    Consulte os headers `X-RateLimit-Limit` e `X-RateLimit-Remaining` em cada resposta.

    ## Cache

    Respostas são cacheadas por **5 minutos** na edge (Cloudflare).
    Para requisições condicionais, utilize `If-None-Match` com o valor do header `ETag` retornado.

    ## Envelope de Resposta

    Todas as respostas seguem o envelope:
    ```json
    {
      "success": true,
      "notice": "...",
      "data": [...],
      "count": 5,
      "total": 25
    }
    ```

    ## Disclaimer

    Dados fornecidos para fins informativos e podem estar desatualizados.
    A bitsARK não garante precisão. Sempre verifique com a corretora oficial.
    Termos completos: https://bitsark.com/terms
  version: 1.0.0
  contact:
    name: bitsARK Support
    email: support@bitsark.com
    url: https://bitsark.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://bitsark.com/terms

externalDocs:
  description: Documentação bitsARK
  url: https://bitsark.com/docs

servers:
  - url: https://api.bitsark.com/v1
    description: Produção

security: []

tags:
  - name: Exchanges
    description: Corretoras indexadas com dados fiscais, regulatórios e de tarifas
  - name: Internal
    description: Endpoints internos — requerem header `X-Internal-Token`

paths:
  /exchanges:
    get:
      operationId: listExchanges
      tags: [Exchanges]
      summary: Lista todas as corretoras
      description: |
        Retorna todas as corretoras indexadas com dados completos de tributação,
        regulação BCB e tarifas. Múltiplos filtros são combinados com lógica AND.
      parameters:
        - $ref: '#/components/parameters/brazil_registered'
        - $ref: '#/components/parameters/bcb_licensed'
        - $ref: '#/components/parameters/accepts_pix'
        - $ref: '#/components/parameters/tax_regime'
      responses:
        '200':
          description: Lista de corretoras obtida com sucesso
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeListResponse'
              examples:
                success:
                  $ref: '#/components/examples/ExchangeListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /exchanges/fees:
    get:
      operationId: listExchangeFees
      tags: [Exchanges]
      summary: Projeção de tarifas de todas as corretoras
      description: |
        Retorna uma projeção reduzida contendo apenas identidade e tarifas de cada corretora.
        Ideal para comparações rápidas sem carregar todos os campos.
        Suporta os mesmos filtros de `/exchanges`.
      parameters:
        - $ref: '#/components/parameters/brazil_registered'
        - $ref: '#/components/parameters/bcb_licensed'
        - $ref: '#/components/parameters/accepts_pix'
        - $ref: '#/components/parameters/tax_regime'
      responses:
        '200':
          description: Projeção de tarifas obtida com sucesso
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ExchangeFee'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /exchanges/brazil-registered:
    get:
      operationId: listBrazilRegisteredExchanges
      tags: [Exchanges]
      summary: Lista corretoras registradas no Brasil
      description: Atalho conveniente para `GET /exchanges?brazil_registered=true`.
      responses:
        '200':
          description: Corretoras registradas no Brasil
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeListResponse'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /exchanges/{id}:
    get:
      operationId: getExchange
      tags: [Exchanges]
      summary: Obtém dados de uma corretora
      description: Retorna os dados completos de uma corretora pelo seu `id` ou `slug`.
      parameters:
        - name: id
          in: path
          required: true
          description: "Identificador ou slug da corretora (ex: `binance`, `mercado-bitcoin`)"
          schema:
            type: string
            example: binance
      responses:
        '200':
          description: Dados da corretora obtidos com sucesso
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            Cache-Control:
              $ref: '#/components/headers/Cache-Control'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    required: [data]
                    properties:
                      data:
                        $ref: '#/components/schemas/Exchange'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /exchanges/dolarmap:
    get:
      operationId: listDolarmapExchanges
      tags: [Internal]
      summary: Lista corretoras monitoradas pelo DolarMap
      description: |
        Endpoint interno. Retorna as corretoras com `monitored_by_dolarmap: true`,
        incluindo o campo `monitored_by_dolarmap` removido das respostas públicas.

        Requer header `X-Internal-Token` com o valor da variável de ambiente `DOLARMAP_SECRET`.
      security:
        - InternalToken: []
      responses:
        '200':
          description: Lista de corretoras DolarMap
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    required: [data]
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/ExchangeInternal'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    InternalToken:
      type: apiKey
      in: header
      name: X-Internal-Token
      description: Token secreto para endpoints internos (`DOLARMAP_SECRET`).

  parameters:
    brazil_registered:
      name: brazil_registered
      in: query
      description: Filtra corretoras com CNPJ registrado no Brasil
      schema:
        type: boolean
      example: true

    bcb_licensed:
      name: bcb_licensed
      in: query
      description: Filtra corretoras autorizadas pelo Banco Central do Brasil
      schema:
        type: boolean
      example: false

    accepts_pix:
      name: accepts_pix
      in: query
      description: Filtra corretoras que aceitam depósitos/saques via PIX
      schema:
        type: boolean
      example: true

    tax_regime:
      name: tax_regime
      in: query
      description: Filtra pelo regime tributário aplicável ao usuário brasileiro
      schema:
        $ref: '#/components/schemas/TaxRegime'
      example: domestic_exchange

  headers:
    ETag:
      description: Hash SHA-256 do body para cache condicional via `If-None-Match`
      schema:
        type: string
        example: '"a1b2c3d4e5f67890"'

    X-Cache:
      description: Status do cache na edge Cloudflare
      schema:
        type: string
        enum: [HIT, MISS]
        example: HIT

    X-RateLimit-Limit:
      description: Máximo de requisições permitidas por minuto
      schema:
        type: integer
        example: 60

    X-RateLimit-Remaining:
      description: Requisições restantes na janela atual
      schema:
        type: integer
        example: 58

    Cache-Control:
      description: Diretivas de cache HTTP
      schema:
        type: string
        example: public, max-age=300, stale-while-revalidate=60, stale-if-error=86400

    Retry-After:
      description: Timestamp Unix de quando o rate limit será redefinido
      schema:
        type: integer
        example: 1748470800

  responses:
    BadRequest:
      description: Requisição inválida
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            notice: "Data is provided for informational purposes only..."
            error: "Invalid query parameter value."

    Unauthorized:
      description: Token inválido ou ausente
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            notice: "Data is provided for informational purposes only..."
            error: "Unauthorized."

    NotFound:
      description: Corretora não encontrada
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            notice: "Data is provided for informational purposes only..."
            error: "Exchange not found."

    RateLimitExceeded:
      description: Rate limit excedido — aguarde antes de tentar novamente
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorResponse'
          example:
            success: false
            notice: "Data is provided for informational purposes only..."
            error: "Rate limit exceeded. Maximum 60 requests per minute."
            retry_after: 1748470800

    InternalServerError:
      description: Erro interno do servidor
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            notice: "Data is provided for informational purposes only..."
            error: "Internal server error."

  schemas:
    TaxRegime:
      type: string
      enum:
        - domestic_exchange
        - domestic_exchange_foreign_origin
        - offshore_law_14754
      description: |
        Regime tributário aplicável ao usuário brasileiro:
        - `domestic_exchange` — corretora doméstica (ex: Mercado Bitcoin)
        - `domestic_exchange_foreign_origin` — doméstica de origem estrangeira (ex: Binance BR)
        - `offshore_law_14754` — offshore sujeita à Lei 14.754/2023

    OperationalDetailsBR:
      type: object
      required: [cnpj, bcb_authorized, accepts_pix, main_jurisdiction_iso]
      properties:
        cnpj:
          type: ["string", "null"]
          description: CNPJ registrado no Brasil. `null` para corretoras sem registro.
          pattern: '^\d{2}\.\d{3}\.\d{3}/\d{4}-\d{2}$'
          example: "45.165.233/0001-82"
        bcb_authorized:
          type: boolean
          description: Possui autorização do Banco Central do Brasil
          example: false
        accepts_pix:
          type: boolean
          description: Aceita depósitos/saques via PIX
          example: true
        main_jurisdiction_iso:
          type: string
          description: Código ISO 3166-1 alpha-2 da jurisdição principal
          minLength: 2
          maxLength: 2
          example: SC

    FiscalDetailsBR:
      type: object
      required:
        - tax_regime
        - monthly_brl_trade_exemption
        - exchange_rfb_reports
        - user_rfb_action_monthly
      properties:
        tax_regime:
          $ref: '#/components/schemas/TaxRegime'
        monthly_brl_trade_exemption:
          type: integer
          description: Limite mensal em BRL isento de imposto. Zero indica ausência de isenção.
          minimum: 0
          example: 35000
        exchange_rfb_reports:
          type: array
          description: Obrigações acessórias da corretora junto à Receita Federal
          items:
            type: string
            enum:
              - in_1888_monthly
              - decripto_annually
          example: ["in_1888_monthly"]
        user_rfb_action_monthly:
          type: array
          description: Ações mensais que o usuário deve tomar junto à Receita Federal
          items:
            type: string
            enum:
              - report_in1888_if_traded_over_30k
              - pay_darf_if_profit
          example: ["report_in1888_if_traded_over_30k", "pay_darf_if_profit"]

    LocalizedNote:
      type: object
      description: Observações sobre descontos, tiers ou condições especiais, localizadas por idioma
      required: [en, pt]
      properties:
        en:
          type: string
          description: Texto em inglês
          maxLength: 512
          example: "25% discount when paying fees with BNB."
        pt:
          type: string
          description: Texto em português do Brasil
          maxLength: 512
          example: "25% de desconto ao pagar as taxas com BNB."

    ExchangeFees:
      type: object
      required: [maker, taker, fee_url, note]
      properties:
        maker:
          type: ["number", "null"]
          description: Taxa maker como proporção de 0 a 1 (ex 0.001 = 0.1%). `null` se indisponível.
          minimum: 0
          maximum: 1
          example: 0.001
        taker:
          type: ["number", "null"]
          description: Taxa taker como proporção de 0 a 1. `null` se indisponível.
          minimum: 0
          maximum: 1
          example: 0.001
        fee_url:
          type: string
          format: uri
          description: URL oficial com a tabela de tarifas da corretora
          example: https://www.binance.com/pt-BR/fee/schedule
        note:
          $ref: '#/components/schemas/LocalizedNote'

    Exchange:
      type: object
      required:
        - id
        - name
        - slug
        - website
        - logo_url
        - analysis_url
        - brazil_registered
        - operational_details_br
        - fiscal_details_br
        - fees
        - updated_at
      properties:
        id:
          type: string
          description: Identificador único da corretora (slug-style)
          example: binance
        name:
          type: string
          description: Nome de exibição da corretora
          example: Binance
        slug:
          type: string
          description: Slug para uso em URLs
          example: binance
        website:
          type: string
          format: uri
          description: Site oficial da corretora
          example: https://www.binance.com
        logo_url:
          type: string
          format: uri
          description: URL do logotipo da corretora
          example: https://assets.bitsark.com/logos/binance.svg
        analysis_url:
          type: string
          format: uri
          description: URL da análise detalhada no bitsARK (injetada pela API)
          example: https://bitsark.com/exchanges/binance/
        brazil_registered:
          type: boolean
          description: Possui CNPJ registrado no Brasil
          example: false
        operational_details_br:
          $ref: '#/components/schemas/OperationalDetailsBR'
        fiscal_details_br:
          $ref: '#/components/schemas/FiscalDetailsBR'
        fees:
          $ref: '#/components/schemas/ExchangeFees'
        updated_at:
          type: string
          format: date-time
          description: Data/hora da última verificação manual dos dados (ISO 8601)
          example: "2026-04-22T21:56:00Z"

    ExchangeInternal:
      allOf:
        - $ref: '#/components/schemas/Exchange'
        - type: object
          required: [monitored_by_dolarmap]
          properties:
            monitored_by_dolarmap:
              type: boolean
              description: Monitorada pelo DolarMap (campo interno, removido das respostas públicas)
              example: true

    ExchangeFee:
      type: object
      description: Projeção reduzida com identidade e tarifas da corretora
      required: [id, name, website, brazil_registered, fees, updated_at]
      properties:
        id:
          type: string
          example: binance
        name:
          type: string
          example: Binance
        website:
          type: string
          format: uri
          example: https://www.binance.com
        brazil_registered:
          type: boolean
          example: false
        fees:
          $ref: '#/components/schemas/ExchangeFees'
        updated_at:
          type: string
          format: date-time
          example: "2026-04-22T21:56:00Z"

    SuccessEnvelope:
      type: object
      required: [success, notice]
      properties:
        success:
          type: boolean
          enum: [true]
          example: true
        notice:
          type: string
          description: Disclaimer padrão sobre os dados
          example: "Data is provided for informational purposes only and may be outdated. BitsARK does not guarantee accuracy. Always verify with the official exchange. Full terms: https://bitsark.com/terms"
        count:
          type: integer
          description: Número de itens na resposta atual
          minimum: 0
          example: 1
        total:
          type: integer
          description: Total de itens no dataset completo
          minimum: 0
          example: 25

    ExchangeListResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, count, total]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Exchange'

    ErrorResponse:
      type: object
      required: [success, notice, error]
      properties:
        success:
          type: boolean
          enum: [false]
          example: false
        notice:
          type: string
          example: "Data is provided for informational purposes only..."
        error:
          type: string
          description: Mensagem de erro legível por humanos
          example: "Exchange not found."

    RateLimitErrorResponse:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          required: [retry_after]
          properties:
            retry_after:
              type: integer
              description: Timestamp Unix indicando quando o rate limit será redefinido
              example: 1748470800

  examples:
    ExchangeListExample:
      summary: Lista com uma corretora (Binance)
      value:
        success: true
        notice: "Data is provided for informational purposes only and may be outdated. BitsARK does not guarantee accuracy. Always verify with the official exchange. Full terms: https://bitsark.com/terms"
        count: 1
        total: 25
        data:
          - id: binance
            name: Binance
            slug: binance
            website: https://www.binance.com
            logo_url: https://assets.bitsark.com/logos/binance.svg
            analysis_url: https://bitsark.com/exchanges/binance/
            brazil_registered: false
            operational_details_br:
              cnpj: "45.165.233/0001-82"
              bcb_authorized: false
              accepts_pix: true
              main_jurisdiction_iso: SC
            fiscal_details_br:
              tax_regime: offshore_law_14754
              monthly_brl_trade_exemption: 0
              exchange_rfb_reports: [decripto_annually]
              user_rfb_action_monthly: [report_in1888_if_traded_over_30k, pay_darf_if_profit]
            fees:
              maker: 0.001
              taker: 0.001
              fee_url: https://www.binance.com/pt-BR/fee/schedule
              note:
                en: "25% discount when paying fees with BNB."
                pt: "25% de desconto ao pagar as taxas com BNB."
            updated_at: "2026-04-22T21:56:00Z"