openapi: 3.1.0
info:
  version: '1.0'
  title: Accounts
  description: API documentation
  contact:
    name: admin
servers:
  - url: https://api.coinsflow.ge
    description: Production
  - url: https://api.sandbox.coinsflow.ge
    description: Sandbox
paths:
  /accounts:
    parameters: []
    get:
      tags:
        - account
      operationId: accounts-list
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
    post:
      tags:
        - account
      summary: Account create
      operationId: account-create
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Account'
  /accounts/{id}/wallets:
    parameters:
      - schema:
          type: string
          format: uuid
        name: id
        in: path
        required: true
        description: Account ID parameter added as part of the URL.
    post:
      summary: Wallet create
      operationId: post-accounts-wallets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Wallet'
      tags:
        - account
      description: >-
        This call allows you to create a dedicated address for your
        account.<br><br>Note: Due to rare timeouts for larger numbers of
        requests, we strongly recommend a "retry logic" to be present
      requestBody:
        $ref: '#/components/requestBodies/Wallet'
    get:
      summary: Wallet list
      operationId: get-accounts-wallets
      parameters:
        - schema:
            type: boolean
          name: withQr
          in: query
          description: >-
            Boolean flag to indicate if you want a QR code details in the
            response.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Wallet'
      tags:
        - account
      description: List of dedicated wallets attached to the account
  /accounts/{id}/balances:
    parameters:
      - schema:
          type: string
          format: uuid
        name: id
        in: path
        required: true
        description: Account ID parameter added as part of the URL.
    get:
      summary: Account balance list
      tags:
        - account
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WalletBalance'
      operationId: get-account-wallets-balances
      description: List of account wallets balances
  /reports/account/operations:
    post:
      summary: Account operations report create
      operationId: report-account-operations-create
      tags:
        - report
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - from
                - to
                - reportFormat
                - accountId
              properties:
                from:
                  type: string
                  format: date
                  description: Start date of the report range.
                to:
                  type: string
                  format: date
                  description: End date of the report range.
                reportFormat:
                  type: string
                  description: Output format for the report, currently CSV supported only.
                accountId:
                  type: string
                  format: uuid
                  description: The account ID.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Report'
  /reports/{reportId}:
    parameters:
      - schema:
          type: string
          format: uuid
        name: reportId
        in: path
        required: true
        description: >-
          Report ID parameter received from [Account operations report
          create](#operation/report-account-operations-create) added as part of
          the URL.
    get:
      summary: Report download
      operationId: report-download
      tags:
        - report
      description: Downloads the generated report file.
      responses:
        '200':
          description: OK
          content:
            text/csv:
              schema:
                type: string
                format: binary
tags:
  - name: account
    description: Endpoints related to account
  - name: report
    description: Endpoints related to reports
components:
  requestBodies:
    Wallet:
      content:
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              asset:
                type: string
                format: uuid
                description: >-
                  This parameter indicates the unique code that identifies the
                  asset.
            required:
              - asset
      description: ''
  securitySchemes:
    HMAC:
      type: apiKey
      description: >-
        # Example bash script

        ```bash

        #!/bin/bash

        set -e

        METHOD=$(echo "$1" | tr a-z A-Z)

        ENDPOINT=$2

        GATEWAY_HOST=API_HOST

        GATEWAY_URL=API_URL

        HMAC_KEY=

        HMAC_SECRET=

        ENDPOINT_URL=$GATEWAY_URL$ENDPOINT

        DATE=$(LC_ALL=en_US.utf8 date --utc +"%a, %d %b %Y %H:%M:%S UTC")

        if [ -z "$METHOD" ] || [ -z "$ENDPOINT" ]

        then

        echo -e "Usage `basename "$0"` METHOD ENDPOINT\nExample GET /endpoint"

        exit 0

        fi

        SIGN_STRING="date: $DATE\n$METHOD $ENDPOINT HTTP/1.1"

        SIGNATURE=$(echo -en $SIGN_STRING | openssl dgst -sha256 -hmac
        "$HMAC_SECRET" -binary | base64)

        curl -s -X "$METHOD" "$ENDPOINT_URL" -H "Host: $GATEWAY_HOST" -H "Date:
        $DATE" -H "Authorization: hmac username=\"$HMAC_KEY\",
        algorithm=\"hmac-sha256\", headers=\"date request-line\",
        signature=\"$SIGNATURE\"" | jq

        ```
      name: Authorization contains username algorithm headers signature
      in: header
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
                description: >-
                  This parameter displays the unique code of the error message
                  produced.
              msg:
                type: string
                description: This parameter describes the message of the error produced.
          examples:
            Example 1:
              value:
                code: -100
                msg: Request data is invalid
  schemas:
    Account:
      type: object
      description: Account object
      properties:
        id:
          type: string
          description: >
            This parameter displays the unique code that identifies the
            resource.
          format: uuid
        createdAt:
          type: string
          description: This parameter displays the date and time the resource was created.
          format: date-time
        accountName:
          type: string
          x-stoplight:
            id: 6saqpp07l469b
          description: This parameter displays the additional optional account name.
    Asset:
      type: object
      description: Asset object
      properties:
        id:
          type: string
          description: >
            This parameter displays the unique code that identifies the crypto
            currency.
          format: uuid
        network:
          type: string
          description: >
            This parameter displays the network where the crypto currency is
            available.
        name:
          type: string
          description: |
            This parameter displays the name given to the crypto currency.
        symbol:
          type: string
          description: >
            This parameter displays the symbol associated to the crypto
            currency.
        contract:
          type:
            - string
            - 'null'
          description: >
            This parameter displays the unique code that identifies the crypto
            currency's contract.
        decimals:
          type: integer
          description: >
            This parameter displays the amount of decimals acepted by the crypto
            currency.
        active:
          type: boolean
          description: >
            This parameter displays the current status of the crypto currency
            (active or inactive) on your account.
      examples:
        - id: 585c16ca-d438-4ef6-bcd2-a6d5ff685af4
          network: ETH_TEST3
          name: USD Coin Test (Goerli)
          symbol: USDC_TEST3
          contract: '0x07865c6E87B9F70255377e024ace6630C1Eaa37F'
          decimals: 6
          active: true
      x-examples:
        Example 1:
          id: 585c16ca-d438-4ef6-bcd2-a6d5ff685af4
          network: ETH_TEST3
          name: USD Coin Test (Goerli)
          symbol: USDC_TEST3
          contract: '0x07865c6E87B9F70255377e024ace6630C1Eaa37F'
          decimals: 6
          active: true
    Wallet:
      type: object
      examples:
        - id: b763a491-3ca3-4fe0-b14e-5c87f201967b
          asset:
            id: c21f664c-d2a1-4b41-9564-25e3dcde497c
            name: Litecoin Test
            symbol: LTC_TEST
            displayName: Litecoin Test
            displaySymbol: LTC_TEST
            exchangeSymbol: LTC
            type: CRYPTO
            subType: BASE_ASSET
            token: false
            contract: null
            nativeAsset: LTC_TEST
            decimals: 8
            network: LTC_TEST
          address: tltc1qar05t4myq978esl36mv7ca3c6czmzq57azymkz
          createdAt: '2023-09-13T13:29:32+00:00'
          qr: >-
            ZGF0YTppbWFnZS9zdmcreG1sO2Jhc2U2NCxQRDk0Yld3Z2RtVnljMmx2YmowaU1TNHdJaUJsYm1OdlpHbHVaejBpVlZSR0xUZ2lQejRL
      description: Wallet object
      title: Wallet
      properties:
        id:
          type: string
          description: This parameter displays the unique code that identifies the wallet.
          format: uuid
        asset:
          $ref: '#/components/schemas/Asset'
          description: Asset object
        address:
          type: string
          description: >-
            This parameter displays the unique code that identifies the location
            of the wallet.
        tag:
          type: string
          description: >-
            This parameter allows you to insert the unique numerical code,
            required by some blockchains, to pair with the deposit address, as
            an additional Security measure (If the Asset requires it, a value is
            displayed, otherwise it is "null").
        createdAt:
          type: string
          description: This parameter displays the date and time the wallet was created.
          format: date-time
        qr:
          type: string
          format: base64
          description: >-
            This parameter displays the base64 encoded qr code that identifies
            the wallet (that you can decode and display as
            data:image/png;base64).
    WalletBalance:
      title: WalletBalance
      x-stoplight:
        id: d405ct1nyz97w
      type: object
      examples:
        - id: 3faafb38-619d-4cee-bc3c-0b5f3f1b4bd8
          wallet:
            id: 2750a4db-cbd6-49a7-9d90-a45ef15c7f49
            address: '0xFb847dd9dC091071865CdE66dA759dFe13eEBAB1'
            createdAt: '2023-09-07T14:46:50+00:00'
          asset:
            id: 8872273c-f1be-4d88-ae04-75faddbdeb5f
            name: Ethereum Test (Goerli)
            symbol: ETH_TEST3
            displayName: Ethereum Test (Goerli)
            displaySymbol: ETH_TEST3
            exchangeSymbol: ETH
            type: CRYPTO
            subType: BASE_ASSET
            token: false
            contract: null
            nativeAsset: ETH_TEST3
            decimals: 18
            network: ETH_TEST3
          available: '0.010000000000000000'
          deposit: '0.010000000000000000'
          depositFee: '0.000000000000000000'
          network: 120
          createdAt: '2023-09-29T04:59:29+00:00'
          updatedAt: null
          availableEur: '4.58'
      properties:
        id:
          type: string
          format: uuid
          description: >-
            This parameter displays the unique code that identifies the
            operation that changed the balance.
        wallet:
          $ref: '#/components/schemas/Wallet'
        asset:
          $ref: '#/components/schemas/Asset'
        available:
          type: string
          description: >-
            This parameter displays the amount available of the crypto currency
            associated with the balance.
        deposit:
          type: string
          description: This parameter displays the amout deposited.
        depositFee:
          type: string
          description: This parameter displays the amout charged as fee.
        network:
          type: string
          description: >-
            This parameter displays the network where the crypto currency is
            available.
        createdAt:
          type: string
          description: >-
            This parameter displays the date and time the operation was created
            that changed the balance.
        updatedAt:
          type: string
          description: >-
            This parameter displays the date and time the operation was updated
            that changed the balance.
        availableEur:
          type: string
          description: >-
            This parameter displays the EUR amount available of the crypto
            currency associated with the balance.
    Report:
      title: Report
      type: object
      description: Report object
      examples:
        - id: 877cedba-3fee-4620-b685-5538f5ea7627
          status: PENDING
          format: CSV
          createdAt: 02-03-2026 20:28:13
          updatedAt: 02-03-2026 20:28:13
          expiredAt: 02-03-2027 20:28:13
      properties:
        id:
          type: string
          format: uuid
          description: This parameter displays the unique code that identifies the report.
        status:
          type: string
          description: >-
            This parameter displays the current status of the report (e.g.
            PENDING).
        format:
          type: string
          description: This parameter displays the format of the report (e.g. CSV).
        createdAt:
          type: string
          description: This parameter displays the date and time the report was created.
        updatedAt:
          type: string
          description: >-
            This parameter displays the date and time the report was last
            updated.
        expiredAt:
          type: string
          description: This parameter displays the date and time the report will expire.
