openapi: 3.1.0
info:
  version: 1.0.0
  title: Lumx API
  description: A cross-border banking API with instant settlements and unmatched liquidity, powered by stablecoins.
servers:
  - url: https://api-sandbox.lumx.io
  - url: https://api.lumx.io
paths:
  /customers:
    get:
      tags:
        - Customers
      summary: Read all customers
      description: This endpoint reads all customers.
      responses:
        "200":
          description: Resources successfully retrieved.
          content:
            application/json:
              examples:
                Individual:
                  $ref: "#/components/examples/CustomerIndividualArrayExample"
                Business:
                  $ref: "#/components/examples/CustomerBusinessArrayExample"
              schema:
                type: object
                properties:
                  data:
                    description: An array containing all customers.
                    type: array
                    items:
                      $ref: "#/components/schemas/CustomerArrayResponse"
      security:
        - apiKey: []
    post:
      tags:
        - Customers
      summary: Create a customer
      description: This endpoint creates a customer.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerRequest"
      responses:
        "201":
          description: Resource successfully created.
          content:
            application/json:
              examples:
                Individual:
                  $ref: "#/components/examples/CustomerCreateIndividualExample"
                Business:
                  $ref: "#/components/examples/CustomerCreateBusinessExample"
              schema:
                $ref: "#/components/schemas/CustomerCreateResponse"
      security:
        - apiKey: []
  "/customers/{id}":
    get:
      tags:
        - Customers
      summary: Read a customer
      description: This endpoint reads a customer.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Customer's unique identifier.
        - name: includeBalances
          in: query
          required: false
          schema:
            type: boolean
          description: Whether to include balances in the response.
      responses:
        "200":
          description: Resource successfully retrieved.
          content:
            application/json:
              examples:
                Individual:
                  $ref: "#/components/examples/CustomerIndividualExample"
                Business:
                  $ref: "#/components/examples/CustomerBusinessExample"
              schema:
                $ref: "#/components/schemas/CustomerResponse"
      security:
        - apiKey: []
  "/customers/{id}/documents":
    post:
      tags:
        - Customers
      summary: Upload a document
      description: This endpoint uploads a document necessary to verify a customer.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Customer's unique identifier.
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/CustomerUploadDocumentRequest"
      responses:
        "200":
          description: Resource successfully accepted.
      security:
        - apiKey: []
  "/customers/{id}/verifications":
    get:
      tags:
        - Customers
      summary: Read a customer verification
      description: This endpoint reads a customer verification.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Customer's unique identifier.
      responses:
        "200":
          description: Resource successfully retrieved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerVerificationResponse"
      security:
        - apiKey: []
    post:
      tags:
        - Customers
      summary: Start a customer verification
      description: This endpoint starts a customer verification.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Customer's unique identifier.
      responses:
        "202":
          description: Resource successfully started.
      security:
        - apiKey: []
  /exchange-rates:
    post:
      tags:
        - Exchange Rates
      summary: Get an exchange rate
      description: This endpoint returns an exchange rate quote between two currencies.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExchangeRateRequest"
      responses:
        "200":
          description: Resource successfully retrieved.
          content:
            application/json:
              examples:
                Floating:
                  value:
                    type: "floating"
                    sourceCurrency: "BRL"
                    sourceAmount: "60000.00"
                    targetCurrency: "USDC"
                    targetAmount: "10125.727780"
                    rate: "5.9255"
                Locked:
                  value:
                    id: "123e4567-e89b-12d3-a456-426614174001"
                    type: "locked"
                    expiresAt: "2026-05-05T00:00:00Z"
                    sourceCurrency: "BRL"
                    sourceAmount: "5925.55"
                    targetCurrency: "USDC"
                    targetAmount: "10000.000000"
                    rate: "5.9255"
              schema:
                $ref: "#/components/schemas/ExchangeRateResponse"
      security:
        - apiKey: []
  /transactions:
    get:
      tags:
        - Transactions
      summary: Read all transactions
      description: This endpoint reads all of your transactions.
      responses:
        "200":
          description: Resources successfully retrieved.
          content:
            application/json:
              examples:
                "On-ramp - Awaiting funds":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOnrampAwaitingFundsExample/value"
                "On-ramp - Processing":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOnrampProcessingExample/value"
                "On-ramp - Success":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOnrampSuccessExample/value"
                "On-ramp - Failed":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOnrampFailedExample/value"
                "Off-ramp - Awaiting funds":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOfframpAwaitingFundsExample/value"
                "Off-ramp - Processing":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOfframpProcessingExample/value"
                "Off-ramp - Success":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionOfframpSuccessExample/value"
                "Transfer - Processing":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionTransferProcessingExample/value"
                "Transfer - Success":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionTransferSuccessExample/value"
                "Transfer - Failed":
                  value:
                    data:
                      - $ref: "#/components/examples/TransactionTransferFailedExample/value"
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: An array containing all transactions.
                    items:
                      oneOf:
                        - type: object
                          title: On-ramps
                          allOf:
                            - $ref: "#/components/schemas/TransactionOnRampResponse"
                            - $ref: "#/components/schemas/TransactionTimestamps"
                        - type: object
                          title: Off-ramps
                          allOf:
                            - $ref: "#/components/schemas/TransactionOffRampResponse"
                            - $ref: "#/components/schemas/TransactionTimestamps"
                        - type: object
                          title: Transfers
                          allOf:
                            - $ref: "#/components/schemas/TransactionTransferResponse"
                            - $ref: "#/components/schemas/TransactionTimestamps"
      security:
        - apiKey: []
  "/transactions/{id}":
    get:
      tags:
        - Transactions
      summary: Read a transaction
      description: This endpoint reads a transaction.
      parameters:
        - name: id
          in: path
          description: Transaction's unique identifier.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Transaction successfully retrieved.
          content:
            application/json:
              examples:
                "On-ramp - Awaiting funds":
                  $ref: "#/components/examples/TransactionOnrampAwaitingFundsExample"
                "On-ramp - Processing":
                  $ref: "#/components/examples/TransactionOnrampProcessingExample"
                "On-ramp - Success":
                  $ref: "#/components/examples/TransactionOnrampSuccessExample"
                "On-ramp - Failed":
                  $ref: "#/components/examples/TransactionOnrampFailedExample"
                "Off-ramp - Awaiting funds":
                  $ref: "#/components/examples/TransactionOfframpAwaitingFundsExample"
                "Off-ramp - Processing":
                  $ref: "#/components/examples/TransactionOfframpProcessingExample"
                "Off-ramp - Success":
                  $ref: "#/components/examples/TransactionOfframpSuccessExample"
                "Off-ramp - Failed":
                  $ref: "#/components/examples/TransactionOfframpFailedExample"
                "Transfer - Processing":
                  $ref: "#/components/examples/TransactionTransferProcessingExample"
                "Transfer - Success":
                  $ref: "#/components/examples/TransactionTransferSuccessExample"
                "Transfer - Failed":
                  $ref: "#/components/examples/TransactionTransferFailedExample"
              schema:
                allOf:
                  - $ref: "#/components/schemas/TransactionResponse"
                  - $ref: "#/components/schemas/TransactionTimestamps"
      security:
        - apiKey: []
  /transactions/on-ramp:
    post:
      tags:
        - Transactions
      summary: On-ramp
      description: This endpoint converts fiat to stablecoin.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionOnRampRequest"
      responses:
        "202":
          description: On-ramp transaction started successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/TransactionOnRampResponse"
                  - $ref: "#/components/schemas/TransactionTimestamps"
      security:
        - apiKey: []
  /transactions/off-ramp:
    post:
      tags:
        - Transactions
      summary: Off-ramp
      description: This endpoint converts stablecoins to fiat.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionOffRampRequest"
      responses:
        "202":
          description: Off-ramp transaction started successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/TransactionOffRampResponse"
                  - $ref: "#/components/schemas/TransactionTimestamps"
      security:
        - apiKey: []
  /transactions/transfer:
    post:
      tags:
        - Transactions
      summary: Transfer
      description: This endpoint starts a transfer of funds between customers.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionTransferRequest"
      responses:
        "202":
          description: Transfer transaction started successfully.
          content:
            application/json:
              example:
                $ref: "#/components/examples/TransactionTransferProcessingExample"
              schema:
                allOf:
                  - $ref: "#/components/schemas/TransactionTransferResponse"
                  - $ref: "#/components/schemas/TransactionTimestamps"
      security:
        - apiKey: []
components:
  examples:
    CustomerIndividualArrayExample:
      value:
        data:
          - id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            type: "individual"
            name: "William Default"
            taxId: "123.456.789-00"
            birthDate: "1990-01-01"
            country: "BRA"
            email: "william.default@example.com"
            walletAddress: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
            verification:
              status: "pending"
              level: "standard"
            transactionLimits:
              single: "1000.00"
              daily: "10000.00"
              monthly: "100000.00"
            createdAt: "2021-01-01T00:00:00Z"
            updatedAt: "2021-01-01T00:00:00Z"
    CustomerBusinessArrayExample:
      value:
        data:
          - id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            type: "business"
            legalName: "Lumx S.A"
            taxId: "42.887.120/0001-00"
            incorporationDate: "2020-01-01"
            country: "BRA"
            email: "hello@lumx.io"
            walletAddress: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
            compliance:
              status: "pending"
              level: "standard"
              transactionLimits:
                single: "1000.00"
                daily: "10000.00"
                monthly: "100000.00"
            createdAt: "2021-01-01T00:00:00Z"
            updatedAt: "2021-01-01T00:00:00Z"  
    CustomerIndividualExample:
      value:
        id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "individual"
        name: "William Default"
        taxId: "123.456.789-00"
        birthDate: "1990-01-01"
        country: "BRA"
        email: "william.default@example.com"
        walletAddress: "0x1234567890123456789012345678901234567890"
        blockExplorerUrl: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
        balances:
          - currency: "USDC"
            amount: "10000.000000"
            updatedAt: "2021-01-01T00:00:00Z"
          - currency: "USDT"
            amount: "10000.000000"
            updatedAt: "2021-01-01T00:00:00Z"
        verification:
          status: "pending"
          level: "standard"
        transactionLimits:
            single: "1000.00"
            daily: "10000.00"
            monthly: "100000.00"
        createdAt: "2021-01-01T00:00:00Z"
        updatedAt: "2021-01-01T00:00:00Z"
    CustomerBusinessExample:
      value:
        id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "business"
        legalName: "Lumx S.A"
        taxId: "42.887.120/0001-00"
        incorporationDate: "2020-01-01"
        country: "BRA"
        email: "hello@lumx.io"
        beneficiaries:
          - id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            type: "individual"
            name: "William Default"
            taxId: "123.456.789-00"
            birthDate: "1990-01-01"
            country: "BRA"
            email: "william.default@example.com"
            sharePercentage: 20
        walletAddress: "0x1234567890123456789012345678901234567890"
        blockExplorerUrl: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
        balances:
          - currency: "USDC"
            amount: "10000.000000"
            updatedAt: "2021-01-01T00:00:00Z"
          - currency: "USDT"
            amount: "10000.000000"
            updatedAt: "2021-01-01T00:00:00Z"
        verification:
          status: "pending"
          level: "standard"
        transactionLimits:
          single: "1000.00"
          daily: "10000.00"
          monthly: "100000.00"
        createdAt: "2021-01-01T00:00:00Z"
        updatedAt: "2021-01-01T00:00:00Z"
    CustomerCreateIndividualExample:
       value:
        id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "individual"
        name: "William Default"
        taxId: "123.456.789-00"
        birthDate: "1990-01-01"
        country: "BRA"
        email: "william.default@example.com"
        walletAddress: "0x1234567890123456789012345678901234567890"
        blockExplorerUrl: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
        verification:
          status: "pending"
          level: "standard"
        transactionLimits:
            single: "1000.00"
            daily: "10000.00"
            monthly: "100000.00"
        createdAt: "2021-01-01T00:00:00Z"
        updatedAt: "2021-01-01T00:00:00Z"
    CustomerCreateBusinessExample:
      value:
        id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "business"
        legalName: "Lumx S.A"
        taxId: "42.887.120/0001-00"
        incorporationDate: "2020-01-01"
        country: "BRA"
        email: "hello@lumx.io"
        beneficiaries:
          - id: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            type: "individual"
            name: "William Default"
            taxId: "123.456.789-00"
            birthDate: "1990-01-01"
            country: "BRA"
            email: "william.default@example.com"
            sharePercentage: 20
        walletAddress: "0x1234567890123456789012345678901234567890"
        blockExplorerUrl: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
        verification:
          status: "pending"
          level: "standard"
        transactionLimits:
          single: "1000.00"
          daily: "10000.00"
          monthly: "100000.00"
        createdAt: "2021-01-01T00:00:00Z"
        updatedAt: "2021-01-01T00:00:00Z"
    TransactionOnrampAwaitingFundsExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174000"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "on_ramp"
        request:
          $ref: "#/components/examples/TransactionOnrampRequestExample/value"
        state:
          status: "awaiting_funds"
          payment:
            rail: "pix"
            brCode: "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOnrampProcessingExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174002"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "on_ramp"
        request:
          $ref: "#/components/examples/TransactionOnrampRequestExample/value"
        state:
          status: "success"
          payment:
            rail: "pix"
            brCode: "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOnrampSuccessExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174002"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "on_ramp"
        request:
          $ref: "#/components/examples/TransactionOnrampRequestExample/value"
        state:
          status: "processing"
          payment:
            rail: "pix"
            brCode: "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
          receipt:
            rate: "6.0066"
            sourceAmount: "1000.000000"
            targetAmount: "5925.55"
            sourceCurrency: "USDC"
            targetCurrency: "BRL"
            fees:
              currency: "USDC"
              lumx:
                percentage: "10.000000"
                flat: "1"
              developer:
                percentage: "0.000000"
                flat: "0"
          blockchain:
            transactionHash: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl: "https://amoy.polygonscan.com/tx/0x1234567890123456789012345678901234567890"
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOnrampFailedExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174002"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "on_ramp"
        request:
          $ref: "#/components/examples/TransactionOnrampRequestExample/value"
        state:
          status: "failed"
          payment:
            rail: "pix"
            brCode: "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-4266141740005204000053039865802BR5915Test Merchant6009Sao Paulo62070503***63041234"
          error: {}
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOfframpAwaitingFundsExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174003"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "off_ramp"
        request:
          $ref: "#/components/examples/TransactionOfframpRequestExample/value"
        state:
          status: "awaiting_funds"
          payment:
            rail: "pix"
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOfframpProcessingExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174003"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "on_ramp"
        request:
          $ref: "#/components/examples/TransactionOfframpRequestExample/value"
        state:
          status: "processing"
          payment:
            rail: "pix"
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOfframpSuccessExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174003"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "off_ramp"
        request:
          $ref: "#/components/examples/TransactionOfframpRequestExample/value"
        state:
          status: "success"
          payment:
            rail: "pix"
          receipt:
            rate: "6.0066"
            sourceAmount: "1000.00"
            targetAmount: "5925.55"
            sourceCurrency: "USDC"
            targetCurrency: "BRL"
            fees:
              currency: "USDC"
              lumx:
                percentage: "10.000000"
                flat: "1"
              developer:
                percentage: "0.000000"
                flat: "0"
          blockchain:
            transactionHash: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl: "https://amoy.polygonscan.com/tx/0x1234567890123456789012345678901234567890"
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionOfframpFailedExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174003"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "off_ramp"
        request:
          $ref: "#/components/examples/TransactionOfframpRequestExample/value"
        state:
          status: "failed"
          payment:
            rail: "pix"
          error: {}
        createdAt: "2024-03-20T15:30:00Z"
        updatedAt: "2024-03-20T15:30:05Z"
    TransactionTransferProcessingExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174004"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "transfer"
        request:
          currency: "USDC"
          from: "123e4567-e89b-12d3-a456-426614174001"
          to: "123e4567-e89b-12d3-a456-426614174002"
          amount: "1000.000000" 
        state:
          status: "processing"
    TransactionTransferSuccessExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174004"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "transfer"
        request:
          currency: "USDC"
          from: "123e4567-e89b-12d3-a456-426614174001"
          to: "123e4567-e89b-12d3-a456-426614174002"
          amount: "1000.000000" 
        state:
          status: "success"
          blockchain:
            transactionHash: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl: "https://amoy.polygonscan.com/tx/0x1234567890123456789012345678901234567890"
    TransactionTransferFailedExample:
      value:
        id: "123e4567-e89b-12d3-a456-426614174004"
        customerId: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type: "transfer"
        request:
          currency: "USDC"
          from: "123e4567-e89b-12d3-a456-426614174001"
          to: "123e4567-e89b-12d3-a456-426614174002"
          amount: "1000.000000"
        state:
          status: "failed"
          error: {}
    TransactionOnrampRequestExample:
      value:
        sourceCurrency: "BRL"
        sourceAmount: "10000.00"
        targetCurrency: "USDC"
        payment:
          rail: "pix"
    TransactionOfframpRequestExample:
      value:
        sourceCurrency: "BRL"
        sourceAmount: "10000.00"
        targetCurrency: "BRL"
        payment:
          rail: "pix"
          keyType: "cpf"
          keyValue: "123.456.789-00"
  schemas:
    CustomerRequest:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: Customer's unique identifier.
              format: uuid
              readOnly: true
        - oneOf:
            - allOf:
                - type: object
                  description: Customer type is individual.
                  title: Individual
                - $ref: "#/components/schemas/CustomerIndividual"
            - allOf:
              - type: object
                description: Customer type is business.
                title: Business
              - $ref: "#/components/schemas/CustomerBusiness"
              - type: object
                properties:
                  beneficiaries:
                    type: array
                    description: List of beneficiaries associated with this business. Only individuals with a share percentage of 20% or greater are required.
                    items: 
                      type: object 
                      allOf:
                        - $ref: "#/components/schemas/CustomerIndividual"
                        - type: object
                          properties:
                            type:
                              description: Beneficiary's type.
                            name:
                              description: Beneficiary's name.
                            taxId:
                              description: Beneficiary's tax ID.
                            birthDate:
                              description: Beneficiary's birth date.
                            country:
                              description: Beneficiary's country.
                            email:
                              description: Beneficiary's email.
                            sharePercentage:
                              type: number
                              description: The share percentage of the beneficiary.
                              example: 20
                        - required:
                            - type
                            - name
                            - taxId
                            - birthDate
                            - country
                            - email
                            - sharePercentage
      required:
        - id
        - type
        - name
        - legalName
        - taxId
        - birthDate
        - email
        - country
        - incorporationDate
        - beneficiaries
    CustomerResponse:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: Customer's unique identifier.
              format: uuid
              readOnly: true
        - oneOf:
            - $ref: "#/components/schemas/CustomerIndividual"
              description: Customer type is individual.
              title: Individual
            - allOf:
                - type: object
                  description: Customer type is business.
                  title: Business
                - $ref: "#/components/schemas/CustomerBusiness"
                - type: object
                  properties:
                    beneficiaries:
                      type: array
                      description: List of beneficiaries associated with this business.
                      items: 
                        type: object 
                        allOf:
                          - $ref: "#/components/schemas/CustomerIndividual"
                          - type: object
                            properties:
                              id:
                                type: string
                                description: Beneficiary's unique identifier.
                                format: uuid
                                example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                              type:
                                description: Beneficiary's type.
                              name:
                                description: Beneficiary's name.
                              taxId:
                                description: Beneficiary's tax ID.
                              birthDate:
                                description: Beneficiary's birth date.
                              country:
                                description: Beneficiary's country.
                              email:
                                description: Beneficiary's email.
                              sharePercentage:
                                type: number
                                description: The share percentage of the beneficiary.
                                example: 20
        - type: object
          properties:
            taxId:
              description: Customer's tax ID.
            walletAddress:
              type: string
              description: Customer's wallet address.
              example: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl:
              type: string
              description: Customer's block explorer URL.
              example: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
            balances:
              type: array
              items:
                $ref: "#/components/schemas/CustomerBalance"
            verification:
              $ref: "#/components/schemas/CustomerVerification"
            transactionLimits:
              type: object
              description: Verification's transaction limits.
              properties:
                single:
                  type: string
                  description: Single transaction limit for the customer's KYC.
                  example: "1000.00"
                daily:
                  type: string
                  description: Daily limit for the customer's KYC.
                  example: "10000.00"
                monthly:
                  type: string
                  description: Monthly limit for the customer's KYC.
                  example: "100000.00"
            createdAt:
              type: string
              description: Creation date and time.
              format: date-time
              example: "2021-01-01T00:00:00Z"
            updatedAt:
              type: string
              description: Last update date and time.
              format: date-time
              example: "2021-01-01T00:00:00Z"
    CustomerArrayResponse:
      allOf:
        - type: object
          properties:
            id:
              type: string
              description: Customer's unique identifier.
              format: uuid
        - oneOf:
          - allOf:
            - type: object
              description: Customer type is individual.
              title: Individual
            - $ref: "#/components/schemas/CustomerIndividual"
          - allOf:
            - type: object
              description: Customer type is business.
              title: Business
            - $ref: "#/components/schemas/CustomerBusiness"
        - type: object
          properties:
            taxId:
              description: Customer's tax ID.
            walletAddress:
              type: string
              description: Customer's wallet address.
              example: "0x1234567890123456789012345678901234567890"
            blockExplorerUrl:
              type: string
              description: Customer's block explorer URL.
              example: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
            verification:
              $ref: "#/components/schemas/CustomerVerification"
            transactionLimits:
              type: object
              description: Customer's transaction limits.
              properties:
                single:
                  type: string
                  description: Single transaction limit for the customer's KYC.
                  example: "1000.00"
                daily:
                  type: string
                  description: Daily limit for the customer's KYC.
                  example: "10000.00"
                monthly:
                  type: string
                  description: Monthly limit for the customer's KYC.
                  example: "100000.00"
            createdAt:
              type: string
              description: Creation date and time.
              format: date-time
              example: "2021-01-01T00:00:00Z"
            updatedAt:
              type: string
              description: Last update date and time.
              format: date-time
              example: "2021-01-01T00:00:00Z"
    CustomerIndividual:
      type: object
      properties:
        type:
          type: string
          description: Customer's type.
          enum: ["individual"]
          example: "individual"
        name:
          type: string
          description: Customer's full name.
          example: "William Default"
        taxId:
          type: string
          description: Customer's tax ID. It must be a valid tax ID in the country where the customer lives.
          example: "123.456.789-00"
        birthDate:
          type: string
          description: Customer's birth date.
          format: date
          example: "1990-01-01"
        country:
          type: string
          description: Customer's country using ISO 3166-1 alpha-3 code.
          enum: ["BRA"]
          example: "BRA"
        email:
          type: string
          description: Customer's email.
          example: "william.default@example.com"
    CustomerBusiness:
      type: object
      properties:
        type:
          type: string
          description: Customer's type.
          enum: ["business"]
        legalName:
          type: string
          description: Customer legal name.
          example: "Lumx S.A"
        taxId:
          type: string
          description: Customer's tax ID. It must be a valid tax ID in the country where the company is incorporated.
          example: "42.887.120/0001-00"
        incorporationDate:
          type: string
          description: Customer incorporation date.
          format: date
          example: "2020-01-01"
        country:
          type: string
          description: Customer's country using ISO 3166-1 alpha-3 code.
          example: "BRA"
        email:
          type: string
          description: Customer's email.
          example: "hello@lumx.io"
    CustomerVerification:
      type: object
      description: Customer's verification KYC/KYB.
      properties:
        status:
          type: string
          description: Verification's status.
          enum:
            ["pending", "approved", "final_rejection", "temporary_rejection"]
          example: "pending"
        level:
          type: string
          description: Verification's level.
          enum: ["standard"]
          example: "standard"
    CustomerBalance:
      type: object
      description: Customer's balance.
      properties:
        currency:
          type: string
          description: Balance's currency.
          enum: [USDC, USDT]
        amount:
          type: string
          description: Balance's amount.
          example: "1000.00"
        updatedAt:
          type: string
          description: Last update date and time.
          example: "2021-01-01T00:00:00Z"
    CustomerCreateResponse:
      allOf:
          - type: object
            properties:
              id:
                type: string
                description: Customer's unique identifier.
                format: uuid
                readOnly: true
          - oneOf:
              - $ref: "#/components/schemas/CustomerIndividual"
                description: Customer type is individual.
                title: Individual
              - allOf:
                  - type: object
                    description: Customer type is business.
                    title: Business
                  - $ref: "#/components/schemas/CustomerBusiness"
                  - type: object
                    properties:
                      beneficiaries:
                        type: array
                        description: List of beneficiaries associated with this business.
                        items: 
                          type: object 
                          allOf:
                            - $ref: "#/components/schemas/CustomerIndividual"
                            - type: object
                              properties:
                                id:
                                  type: string
                                  description: Beneficiary's unique identifier.
                                  format: uuid
                                  example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
                                type:
                                  description: Beneficiary's type.
                                name:
                                  description: Beneficiary's name.
                                taxId:
                                  description: Beneficiary's tax ID.
                                email:
                                  description: Beneficiary's email.
                                birthDate:
                                  description: Beneficiary's birth date.
                                country:
                                  description: Beneficiary's country.
                                sharePercentage:
                                  type: number
                                  description: The share percentage of the beneficiary.
                                  example: 20
          - type: object
            properties:
              taxId:
                description: Customer's tax ID.
              walletAddress:
                type: string
                description: Customer's wallet address.
                example: "0x1234567890123456789012345678901234567890"
              blockExplorerUrl:
                type: string
                description: Customer's block explorer URL.
                example: "https://amoy.polygonscan.com/address/0x1234567890123456789012345678901234567890"
              verification:
                $ref: "#/components/schemas/CustomerVerification"
              transactionLimits:
                type: object
                description: Verification's transaction limits.
                properties:
                  single:
                    type: string
                    description: Single transaction limit for the customer's KYC.
                    example: "1000.00"
                  daily:
                    type: string
                    description: Daily limit for the customer's KYC.
                    example: "10000.00"
                  monthly:
                    type: string
                    description: Monthly limit for the customer's KYC.
                    example: "100000.00"
              createdAt:
                type: string
                description: Creation date and time.
                format: date-time
                example: "2021-01-01T00:00:00Z"
              updatedAt:
                type: string
                description: Last update date and time.
                format: date-time
                example: "2021-01-01T00:00:00Z"
    CustomerUploadDocumentRequest:
      type: object
      properties:
        file:
          type: string
          description: Document's file to be uploaded. The maximum size is 5MB.
          format: binary
          # contentEncoding: binary
        metadata:
          type: object
          description: Document's metadata of the file.
          properties:
            type:
              type: string
              description: Document type.
              enum: [id_card, passport, drivers_license, utility_bill, incorporation_articles, proof_of_address]
              example: "id_card"
            country:
              type: string
              description: Document country using ISO 3166-1 alpha-3 code.
              example: "BRA"
            side:
              type: string
              description: Document side. Only required for documents with both sides.
              nullable: true
              enum: [front_side, back_side]
              example: "front_side"
            beneficiaryId:
              type: string
              description: Beneficiary's unique identifier. Only required for documents of beneficiaries.
              nullable: true
              format: uuid
              example: "123e4567-e89b-12d3-a456-426614174000"
          required:
            - type
            - country
      required:
        - file
        - metadata
    CustomerVerificationResponse:
      type: object
      properties:
        customerId:
          type: string
          description: Customer's unique identifier.
          format: uuid
        status:
          type: string
          description: Customer verification's status.
          enum: ["pending", "approved", "final_rejection", "temporary_rejection"]
          example: "temporary_rejection"
        level:
          type: string
          description: Customer verification's level.
          example: "standard"
          enum: ["standard"]
        statusReason:
          type: object
          description: Customer verification's status reason.
          properties:
            rejectLabels:
              type: array
              description: Customer verification's reject labels.
              example:
                - screenshot
                - unsatisfactory_photos
            rejectSubLabels:
              type: array
              description: Customer verification's reject sub labels.
              example:
                - proofOfAddress_listOfDocs
                - badPhoto
                - proofOfAddress
                - differentDocs
                - badPhoto_screenshot
    ExchangeRateRequest:
      allOf:
        - oneOf:
            - allOf:
                - type: object
                  description: Exchange rate type is floating.
                  title: Floating
                - $ref: "#/components/schemas/ExchangeRateFloating"
            - allOf:
                - type: object
                  description: Exchange rate type is locked.
                  title: Locked
                - $ref: "#/components/schemas/ExchangeRateLocked"
      required:
        - type
        - sourceCurrency
        - sourceAmount
        - targetCurrency  
        - targetAmount
    ExchangeRateResponse:
      allOf:
        - oneOf:
            - allOf:
                - type: object
                  description: Exchange rate type is floating.
                  title: Floating
                  properties:
                    type:
                      type: string
                      description: Exchange rate's type.
                      enum: ["floating"]
                      example: "floating"
                    sourceCurrency:
                      type: string
                      description: Exchange rate's source currency.
                      example: "BRL"
                    sourceAmount:
                      type: string
                      description: Exchange rate's source amount.
                      example: "60000.00"
                    targetCurrency:
                      type: string
                      description: Exchange rate's target currency.
                      example: "USDC"
                    targetAmount:
                      type: string
                      description: Exchange rate's target amount.
                      example: "10125.727780"
            - allOf:
                - type: object
                  description: Exchange rate type is locked.
                  title: Locked
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: Exchange rate's unique identifier.
                      example: "123e4567-e89b-12d3-a456-426614174000"
                    type:
                      type: string
                      description: Exchange rate's type.
                      enum: ["locked"]
                      example: "locked"
                    expiresAt:
                      type: string
                      description: Expiration date and time. The exchange rate duration is 5 minutes.
                      example: "2026-05-05T00:00:00Z"
                    sourceCurrency:
                      type: string
                      description: Exchange rate's source currency.
                      example: "BRL"
                    sourceAmount:
                      type: string
                      description: Exchange rate's source amount.
                      example: "5925.55"
                    targetCurrency:
                      type: string
                      description: Exchange rate's target currency.
                      example: "USDC"
                    targetAmount:
                      type: string
                      description: Exchange rate's target amount.
                      example: "10000.000000"
        - type: object
          properties:
            rate:
              type: string
              description: The exchange rate between the currencies.
              example: "5.9255"
    ExchangeRateFloating:
      type: object
      properties:
        type:
          type: string
          description: Exchange rate's type.
          enum: ["floating"]
          example: "floating"
        sourceCurrency:
          type: string
          enum: [BRL, USDC, USDT]
          description: Exchange rate's source currency.
          example: "BRL"
        sourceAmount:
          type: string
          description: Exchange rate's source amount.
          example: "60000.00"
        targetCurrency:
          type: string
          enum: [BRL, USDC, USDT]
          description: Exchange rate's target currency.
          example: "USDC"
    ExchangeRateLocked:
      type: object
      properties:
        type:
          type: string
          description: Exchange rate's type.
          enum: ["locked"]
          example: "locked"
        sourceCurrency:
          type: string
          enum: [BRL, USDC, USDT]
          description: Exchange rate's source currency.
          example: "BRL"
        targetCurrency:
          type: string
          enum: [BRL, USDC, USDT]
          description: Exchange rate's target currency.
          example: "USDC"
        targetAmount:
          type: string
          description: Exchange rate's target amount.
          example: "10000.000000"
    TransactionResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Transaction's unique identifier.
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
        type:
          type: string
          description: Transaction's type.
          enum: ["on_ramp", "off_ramp", "transfer"]
        request:
          type: object
          description: Transaction's request. See examples for more details.
        state:
          type: object
          description: Transaction's current state. See examples for more details.
    TransactionOnRampRequest:
      allOf:
        - oneOf:
            - allOf:
                - type: object
                  description: On-ramp using floating exchange rate.
                  title: Floating
                - $ref: "#/components/schemas/TransactionOnRampFloating"
            - allOf:
                - type: object
                  description: On-ramp using locked exchange rate.
                  title: Locked
                - $ref: "#/components/schemas/TransactionOnRampLocked"
    TransactionOnRampFloating:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        sourceCurrency:
          type: string
          enum: [BRL]
          description: Transaction's source currency.
          example: "BRL"
        sourceAmount:
          type: string
          description: Transaction's source amount.
          example: "10000.00"
        targetCurrency:
          type: string
          enum: [USDC, USDT]
          description: Transaction's target currency.
          example: "USDC"
        payment:
          type: object
          properties:
            rail:
              type: string
              enum: [pix]
              description: Payment rail to be used.
              example: "pix"
      required:
        - customerId
        - sourceCurrency
        - sourceAmount
        - targetCurrency
        - payment
    TransactionOnRampLocked:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        exchangeRateId:
          type: string
          format: uuid
          description: Exchange rate's id to be used for this transaction.
          example: "123e4567-e89b-12d3-a456-426614174000"
        payment:
          type: object
          properties:
            rail:
              type: string
              enum: [pix]
              description: Payment rail to be used.
              example: "pix"
      required:
        - customerId
        - payment
        - exchangeRateId
    TransactionOnRampResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: On-ramp operation's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type:
          type: string
          description: On-ramp operation's type.
          enum: ["on_ramp"]
          example: "on_ramp"
        request:
          type: object
          properties:
            sourceCurrency:
              type: string
              description: Fiat currency to be converted.
              example: "BRL"
            targetCurrency:
              type: string
              description: Stablecoin to be received.
              example: "USDC"
            amount:
              type: string
              description: Amount to be converted.
              example: "10000.00"
            payment:
              type: object
              properties:
                rail:
                  type: string
                  description: Payment rail to be used.
                  example: "pix"
        state:
          type: object
          description: On-ramp operation's current state. See examples for more details.
    TransactionOffRampRequest:
      allOf:
        - oneOf:
            - allOf:
                - type: object
                  description: Off-ramp using floating exchange rate.
                  title: Floating
                - $ref: "#/components/schemas/TransactionOffRampFloating"
            - allOf:
                - type: object
                  description: Off-ramp using locked exchange rate.
                  title: Locked
                - $ref: "#/components/schemas/TransactionOffRampLocked"
    TransactionOffRampFloating:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        sourceCurrency:
          type: string
          enum: [USDC, USDT]
          description: Transaction's source currency.
          example: "USDC"
        sourceAmount:
          type: string
          description: Transaction's source amount.
          example: "10000.00"
        targetCurrency:
          type: string
          enum: [BRL]
          description: Transaction's target currency.
          example: "BRL"
        payment:
          type: object
          description: The definition of how and where the funds from the off ramp transaction will be sent.
          properties:
            rail:
              type: string
              enum: [pix]
              description: Payment rail to be used.
              example: "pix"
            keyType:
              type: string
              description: Payment rail's key type.
              enum: [cpf, cnpj, email, phone, random]
              example: "cpf"
            keyValue:
              type: string
              description: Payment rail's key value.
              example: "123.456.789-00"
      required:
        - customerId
        - sourceCurrency
        - sourceAmount
        - targetCurrency
        - payment
    TransactionOffRampLocked:
      type: object
      properties:
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        exchangeRateId:
          type: string
          format: uuid
          description: Exchange Rate's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        payment:
          type: object
          description: The definition of how and where the funds from the off ramp transaction will be sent.
          properties:
            rail:
              type: string
              enum: [pix]
              description: Payment rail to be used.
              example: "pix"
            keyType:
              type: string
              description: Payment rail's key type.
              enum: [cpf, cnpj, email, phone, random]
              example: "cpf"
            keyValue:
              type: string
              description: Payment rail's key value.
              example: "123.456.789-00"
      required:
        - customerId
        - payment
        - exchangeRateId
    TransactionOffRampResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Off-ramp operation's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        type:
          type: string
          description: Off-ramp operation's type.
          enum: ["off_ramp"]
          example: "off_ramp"
        request:
          type: object
          properties:
            sourceCurrency:
              type: string
              description: Stablecoin to be converted.
              example: "USDC"
            targetCurrency:
              type: string
              description: Fiat currency to be received.
              example: "BRL"
            amount:
              type: string
              description: Amount to be converted.
              example: "10000.00"
            payment:
              type: object
              properties:
                rail:
                  type: string
                  description: Payment rail to be used.
                  example: "pix"
                keyType:
                  type: string
                  description: Payment rail's key type.
                  enum: [cpf, cnpj, email, phone, random]
                  example: "cpf"
                keyValue:
                  type: string
                  description: Payment rail's key value.
                  example: "123.456.789-00"
        state:
          type: object
          description: Off-ramp operation's current state. See examples for more details.
    TransactionTransferRequest:
      type: object
      properties:
        currency:
          type: string
          enum: [USDC, USDT]
          description: Transfer's currency.
          example: "USDC"
        from:
          type: string
          format: uuid
          description: Customer's unique identifier that will send the tokens.
          example: "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        to:
          oneOf:
            - type: string
              format: uuid
              title: customer
              description: Customer's unique identifier that will receive the tokens.
              example: "980dc26b-42fd-4044-8a42-2271d20a2eb9"
            - type: string
              format: eth-address
              title: address
              description: Blockchain address that will receive the tokens.
              example: "0x1234567890123456789012345678901234567890"
        amount:
          type: string
          description: Transfer's amount.
          example: "10000.000000"
      required:
        - currency
        - amount
        - from
        - to
    TransactionTransferResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Transfer operation's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        customerId:
          type: string
          format: uuid
          description: Customer's unique identifier.
          example: "123e4567-e89b-12d3-a456-426614174000"
        type:
          type: string
          description: Transfer operation's type.
          enum: ["transfer"]
          example: "transfer"
        request:
          type: object
          properties:
            currency:
              type: string
              description: Stablecoin to be transferred.
              example: "USDC"
            from:
              type: string
              format: uuid
              description: Customer's id that will send the tokens.
              example: "123e4567-e89b-12d3-a456-426614174000"
            to:
              type: string
              description: Customer's id that will receive the tokens. Can also be any valid blockchain address.
              example:
                - "123e4567-e89b-12d3-a456-426614174000"
                - "0x1234567890123456789012345678901234567890"
            amount:
              type: string
              description: Amount to be transferred.
              example: "10000.000000"
        state:
          type: object
          description: Transfer operation's current state. See examples for more details.
    TransactionTimestamps:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: Creation date and time.
        updatedAt:
          type: string
          format: date-time
          description: Last update date and time.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Bearer authentication header on the format `Bearer <API_KEY>`.