HitBTC Transactions API

openapi: 3.2.0
info:
  title: Hitbtc Transactions API
  version: ''
  description: 'Operations tagged Transactions across 2 of this provider''s published API definitions: hitbtc-api-v3-spec.yaml, hitbtc-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/3
- url: https://api.hitbtc.com/api/3
  description: Production; the served spec declares the relative server /api/3 and the docs at api.hitbtc.com name this host
- url: https://api.demo.hitbtc.com/api/3
  description: Demo Environment (Sandbox), per api.hitbtc.com docs
tags:
- name: Transactions
paths:
  /wallet/transactions:
    get:
      tags:
      - Transactions
      summary: Get transactions
      description: '⚠️ `from`/`till` and `from_id`/`till_id` are mutually exclusive.


        **Permission**: Payment information


        **IP limit**: 10/10


        **Account limit**: 20/30'
      parameters:
      - $ref: '#/components/parameters/wallet_IdFrom'
      - $ref: '#/components/parameters/wallet_IdTill'
      - $ref: '#/components/parameters/wallet_From'
      - $ref: '#/components/parameters/wallet_Till'
      - $ref: '#/components/parameters/wallet_Sort'
      - $ref: '#/components/parameters/wallet_Limit'
      - $ref: '#/components/parameters/wallet_Offset'
      - name: tx_ids
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/wallet_TransactionID'
        description: Comma-separated list of transaction identifiers.
      - name: currencies
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/wallet_CurrencyCommon'
        description: Comma-separated list of currency codes.
      - name: networks
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/wallet_NetworkCommon'
        description: Comma-separated list of network codes.
      - name: statuses
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/wallet_TransactionStatuses'
        description: Comma-separated list of transaction statuses.
      - name: types
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/wallet_TransactionTypes'
        description: Comma-separated list of transaction types.
      - name: subtypes
        in: query
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/wallet_TransactionSubtypes'
        description: Comma-separated list of transaction subtypes.
      - name: order_by
        in: query
        schema:
          type: string
          default: created_at
          enum:
          - id
          - created_at
          - updated_at
          - last_activity_at
          - ID
          - CREATED_AT
          - UPDATED_AT
          - LAST_ACTIVITY_AT
        description: 'The field the entries sorted by.


          ⚠️ Cannot be `id` or `ID` if `from` and (or) `till` are provided.

          '
      - name: group_transactions
        in: query
        schema:
          type: boolean
          default: false
        description: Flag indicating whether the returned transactions will be parts of a single operation.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/wallet_Transaction'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet_TransactionNotFound'
        '401':
          $ref: '#/components/responses/wallet_401'
        '403':
          $ref: '#/components/responses/wallet_403'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet_TooManyRequests'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet_GatewayTimeout'
        default:
          $ref: '#/components/responses/wallet_Error'
      security:
      - wallet_BearerAuth: []
      - wallet_BasicAuth: []
      operationId: getWalletTransactions
      x-operation-id-source: derived
    servers:
    - url: /api/3
  /wallet/transactions/{id}:
    get:
      tags:
      - Transactions
      summary: Get a transaction
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/wallet_TransactionID'
        description: Transaction bank identifier.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet_Transaction'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/wallet_Validation'
        '401':
          $ref: '#/components/responses/wallet_401'
        '403':
          $ref: '#/components/responses/wallet_403'
        '429':
          $ref: '#/components/responses/wallet_429'
        '504':
          $ref: '#/components/responses/wallet_504'
        default:
          $ref: '#/components/responses/wallet_Error'
      security:
      - wallet_BearerAuth: []
      - wallet_BasicAuth: []
      description: '**Permission**: Payment information


        **IP limit**: 10/10


        **Account limit**: 20/30'
      operationId: getWalletTransactionsById
      x-operation-id-source: derived
    servers:
    - url: /api/3
components:
  schemas:
    wallet_PaymentID:
      title: Payment ID
      type: object
      properties:
        payment_id:
          type: string
          pattern: ^[\w@\-.:<>]+$
          description: An additional recipient identifier (for example, "Memo") required for specific currencies.
    wallet_NotEnoughPermissions:
      title: Not enough permissions
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: Current permission scope in the authentication service is insufficient.
      example:
        error:
          code: 1007
          message: Not enough permissions
    wallet_TransactionStatuses:
      title: Transaction statuses
      type: string
      enum:
      - CREATED
      - PENDING
      - FAILED
      - SUCCESS
      - ROLLED_BACK
      description: "Transaction status.\n\nValues:\n  * `CREATED`—the transaction has been created and needs to be approved. For withdrawals, the status means that the transaction has been created but not committed. It remains in this status until manually validated or moved to a blockchain;\n  * `PENDING`—the transaction has been created and is queued until the fees are paid, and it can be processed further. Also, for withdrawals and deposits, the status means that blockchain confirmations have not yet been gathered;\n  * `FAILED`—the transaction could not be committed;\n  * `ROLLED_BACK`—the transaction has been canceled;\n  * `SUCCESS`—the transaction has been approved and fully processed.\n"
    wallet_TransactionNotFound:
      title: Transaction not found
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: "Any of:\n  * a transaction has failed to create;\n  * the requested transaction is not found.\n"
      example:
        error:
          code: 20004
          message: Transaction not found
          description: ''
    wallet_ShouldUpgradePermission:
      title: Should upgrade permission
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: Current permission scope in the authentication service is insufficient.
      example:
        error:
          code: 1006
          message: Action unavailable, please upgrade scopes
    wallet_BadFormatHS256:
      title: Bad format (HS256)
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: "Any of:\n  * missing required parameters;\n  * the maximum of the time window is exceeded.\n"
      example:
        error:
          code: 1004
          message: Unsupported authorization method
    wallet_PublicComment:
      title: Public comment
      type: object
      properties:
        public_comment:
          type: string
          maxLength: 255
          pattern: ^[\w@\-\.:<>]+( [\w@\-\.:<>]+)*$
          description: 'Custom text comment for external use.


            ℹ️ The specified value will be displayed in the transaction history and may help in identification of the transaction.


            ℹ️ Avoid the following characters: `&`, `''`, `<`, `>`, `"`.

            '
          example: Lorem ipsum dolor sit amet consectetur adipiscing elit...
    wallet_Transfer:
      title: Transfer
      allOf:
      - $ref: '#/components/schemas/wallet_TransactionBase'
      - type: object
        required:
        - native
        properties:
          native:
            $ref: '#/components/schemas/wallet_NativeBase'
    wallet_TransactionTypesBase:
      title: Native transaction types
      type: string
      enum:
      - DEPOSIT
      - WITHDRAW
      - TRANSFER
    wallet_TransactionID:
      title: Transaction ID
      type: string
      format: uuid
      description: Transaction UUID.
      example: 27fa7f14-ca49-42fd-834a-4ce630d069d2
    wallet_AuthInvalid:
      title: Invalid authorization
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: Invalid JWT.
      example:
        error:
          code: 1005
          message: Invalid authorization
    wallet_Address:
      title: Deposit address
      type: object
      properties:
        address:
          $ref: '#/components/schemas/wallet_AddressCommon'
    wallet_TooManyRequests:
      title: Too Many Requests
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: Rate limits are exceeded.
      example:
        error:
          code: 429
          message: Too many requests
    wallet_AirdropTransactionSubtypes:
      title: Airdrop transaction subtypes
      type: string
      enum:
      - AIRDROP
    wallet_NetworkCommon:
      title: Network
      type: string
      description: Network code.
      example: ETH
    wallet_Withdrawal:
      title: Withdrawal
      allOf:
      - $ref: '#/components/schemas/wallet_TransactionBase'
      - type: object
        required:
        - native
        properties:
          native:
            allOf:
            - $ref: '#/components/schemas/wallet_NativeBase'
            - $ref: '#/components/schemas/wallet_NativeWithdrawalFields'
            - $ref: '#/components/schemas/wallet_NativeBlockchainFields'
    wallet_Network:
      title: Network
      type: object
      properties:
        network_code:
          $ref: '#/components/schemas/wallet_NetworkCommon'
    wallet_AddressCommon:
      title: Deposit address
      type: string
      pattern: ^([\w@\-.:<>]+|[0-9A-Z]{4}( ?[0-9A-Z]{4}){8}|(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?)$
      description: Deposit crypto address.
      example: 3A3MR43kUvahSAJtTsxzE8mcTz3VfL9upi
    wallet_Validation:
      title: Validation
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: "Any of:\n  * invalid JSON payload;\n  * invalid form payload;\n  * invalid payload format;\n  * invalid parameter value;\n  * invalid parameter format;\n  * specified parameters are mutually exclusive;\n  * a required parameter is missing;\n  * the value of a parameter is invalid;\n  * provided value is not unique;\n  * in an update request, no parameters provided.\n"
      example:
        error:
          code: 10001
          message: Validation error
    wallet_HashCommon:
      title: Transaction hash
      type: string
      nullable: true
      description: Transaction blockchain hash.
      example: '0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20

        '
    wallet_UnauthorizedBasic:
      title: Unauthorized (Basic)
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: "Any of:\n  * invalid API key;\n  * user is not allowed to perform the requested operation.\n"
      example:
        error:
          code: 1002
          message: Authorization is required or has been failed
    wallet_TransactionSubtypesBase:
      title: Native transaction subtypes
      type: string
      enum:
      - UNCLASSIFIED
      - BLOCKCHAIN
      - OFFCHAIN
      - FIAT
      - WALLET_TO_SPOT
      - SPOT_TO_WALLET
      - CHAIN_SWITCH_FROM
      - CHAIN_SWITCH_TO
    wallet_Currency:
      title: Currency
      properties:
        currency:
          $ref: '#/components/schemas/wallet_CurrencyCommon'
    wallet_GatewayTimeout:
      title: Gateway Timeout
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: Gateway timeout.
      example:
        error:
          code: 22008
          message: Gateway timeout. Please, try again later.
    wallet_Deposit:
      title: Deposit
      allOf:
      - $ref: '#/components/schemas/wallet_TransactionBase'
      - type: object
        required:
        - native
        properties:
          native:
            allOf:
            - $ref: '#/components/schemas/wallet_NativeBase'
            - $ref: '#/components/schemas/wallet_NativeBlockchainFields'
      - type: object
        properties:
          commit_risk:
            $ref: '#/components/schemas/wallet_CommitRisk'
    wallet_TransactionBase:
      title: Transaction
      allOf:
      - type: object
        required:
        - id
        - type
        - status
        - created_at
        - updated_at
        - last_activity_at
        properties:
          id:
            type: integer
            format: int64
            description: Transaction identifier.
            example: 221163
          created_at:
            type: string
            format: date-time
            description: Date and time of the creation.
            example: 2024-03-22 15:04:05Z07:00
          updated_at:
            type: string
            format: date-time
            description: 'Transaction updated.

              '
            example: 2024-03-22 15:04:05Z07:00
          last_activity_at:
            type: string
            format: date-time
            description: "Transaction info updated.\n\n⚠️ `last_activity_at` indicates the timestamp of a history\n record, whereas `updated_at` is the time of the latest actual\n change of transaction info. So `updated_at` may precede\n `last_activity_at` but never updates prior to entire record.\n"
            example: 2024-03-22 15:04:05Z07:00
          status:
            $ref: '#/components/schemas/wallet_TransactionStatuses'
          type:
            $ref: '#/components/schemas/wallet_TransactionTypes'
          subtype:
            $ref: '#/components/schemas/wallet_TransactionSubtypes'
          operation_id:
            type: string
            format: uuid
            description: UUID of the operation embracing the transaction.
            example: 99e78bf4-a708-43a3-ab18-e8e7618cd891
    wallet_Forbidden:
      title: Forbidden
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: "Any of:\n  * currency settings forbid the requested operation;\n  * the user has insufficient permissions for the operation;\n  * requested operation is forbidden for the user;\n  * insufficient API key permissions;\n  * provided IP address is not in the white list;\n  * the user is not eligible for the given currency by the configuration;\n  * provided operation parameters are forbidden by the configuration;\n  * a withdrawal operation failed to pass pre-AML checks.\n"
      example:
        error:
          code: 1003
          message: Action is forbidden for this API key
    wallet_CurrencyCommon:
      title: Cryptocurrency
      type: string
      description: Cryptocurrency code.
      example: USDT
    wallet_CommitRisk:
      title: Commit risk
      type: object
      required:
      - score
      - rbf
      - low_fee
      properties:
        score:
          type: integer
          format: uint64
          nullable: true
          minimum: 0
          maximum: 100
          description: 'Risk score that decreases non-linearly when the transaction gains confirmations.


            ℹ️ Scores from 0 to 50 imply the transaction may be considered committed (but it is not guaranteed) or it may take at least half an hour otherwise.

            '
        rbf:
          type: boolean
          nullable: true
          description: 'Flag indicating whether the transaction did not gain a sufficient number of confirmations and may be replaced by another one for different fees.


            ⚠️ This value indicates the transaction is complete and do not affect the score.


            ℹ️ `false` value along with a score above 50 gives a good chance that the transaction is irreversible.

            '
        low_fee:
          type: boolean
          nullable: true
          description: 'Flag indicating whether the actual network fee is lower than the estimated one.


            ⚠️ This value indicates the difference between the estimated fee and the actual paid fee and does not affect the score.

            '
    wallet_NativeBase:
      title: Native
      allOf:
      - $ref: '#/components/schemas/wallet_Currency'
      - $ref: '#/components/schemas/wallet_Network'
      - type: object
        required:
        - tx_id
        - index
        - currency
        - amount
        properties:
          amount:
            type: string
            description: Transaction amount.
            example: '2.37'
          tx_id:
            $ref: '#/components/schemas/wallet_TransactionID'
          index:
            type: integer
            format: uint64
            description: Last update sequence number.
            example: 1408237221
          protocol_code:
            type: string
            description: The protocol or the standard powering the network.
            example: ETH
    wallet_OTCTransactionTypes:
      title: OTC transaction types
      type: string
      enum:
      - OTC
    wallet_AttemptHashes:
      title: Attempt hashes
      type: string
      description: 'Hash of the attempt to send a transaction to the blockchain.

        '
      example: 0xfb0ba568213d11230cd34d62fddd1cc1fe11fdc173l4f2007b0e47a06ad73d20
    wallet_Error:
      title: Error
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: integer
              format: int
              description: Custom error code.
            message:
              type: string
              description: Error message.
            description:
              type: string
              description: Error description.
    wallet_SubaccountsTransactionSubtypes:
      title: Subaccounts transaction subtypes
      type: string
      enum:
      - SUB_ACCOUNT
    wallet_NativeBlockchainFields:
      title: Native blockchain
      allOf:
      - $ref: '#/components/schemas/wallet_Address'
      - type: object
        required:
        - hash
        - confirmations
        properties:
          hash:
            $ref: '#/components/schemas/wallet_HashCommon'
          confirmations:
            type: integer
            format: uint64
            minimum: 1
            nullable: true
            description: Current count of transaction confirmations.
            example: 2
          senders:
            type: array
            items:
              $ref: '#/components/schemas/wallet_AddressCommon'
            description: Crypto addresses of the transaction senders.
    wallet_BadFormat:
      title: Bad Format
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: Provided parameters do not meet any supported authentication scheme.
      example:
        error:
          code: 1004
          message: Unsupported authorization method
    wallet_TransactionSubtypes:
      title: Transaction subtypes
      allOf:
      - $ref: '#/components/schemas/wallet_TransactionSubtypesBase'
      - $ref: '#/components/schemas/wallet_FuturesTransactionSubtypes'
      - $ref: '#/components/schemas/wallet_AirdropTransactionSubtypes'
      - $ref: '#/components/schemas/wallet_SubaccountsTransactionSubtypes'
      - description: Transaction subtype.
    wallet_FuturesTransactionSubtypes:
      title: Derivatives transaction subtypes
      type: string
      enum:
      - WALLET_TO_DERIVATIVES
      - DERIVATIVES_TO_WALLET
    wallet_Fee:
      title: Withdrawal fee
      type: object
      properties:
        fee:
          type: string
          description: 'Fee amount.


            Format: currency precision

            '
          example: '0'
    wallet_Transaction:
      allOf:
      - type: object
      - title: Transaction
        discriminator:
          propertyName: type
          mapping:
            DEPOSIT: '#/components/schemas/wallet_Deposit'
            WITHDRAW: '#/components/schemas/wallet_Withdrawal'
            TRANSFER: '#/components/schemas/wallet_Transfer'
        oneOf:
        - $ref: '#/components/schemas/wallet_Deposit'
        - $ref: '#/components/schemas/wallet_Withdrawal'
        - $ref: '#/components/schemas/wallet_Transfer'
    wallet_NativeWithdrawalFields:
      title: Native withdrawal
      allOf:
      - $ref: '#/components/schemas/wallet_Fee'
      - $ref: '#/components/schemas/wallet_PublicComment'
      - $ref: '#/components/schemas/wallet_PaymentID'
      - type: object
        required:
        - fee
        properties:
          wallet_id:
            type: string
            pattern: ^*\..*$
            description: Wallet ID.
            example: johndoe.dba.id
          offchain_id:
            type: string
            nullable: true
            description: Identifier of an off-chain withdrawal.
          error_code:
            type: string
            nullable: true
            enum:
            - INVALID_ADDRESS
            - INVALID_PAYMENT_ID
            - BAD_PRECISION
            description: Withdrawal rejection reason.
          attempt_hashes:
            type: array
            items:
              $ref: '#/components/schemas/wallet_AttemptHashes'
    wallet_TransactionTypes:
      title: Transaction types
      allOf:
      - $ref: '#/components/schemas/wallet_OTCTransactionTypes'
      - $ref: '#/components/schemas/wallet_TransactionTypesBase'
      - description: Transaction type.
    wallet_UnauthorizedHS256:
      title: Unauthorized (HS256)
      schema:
        $ref: '#/components/schemas/wallet_Error'
      type: object
      description: "Any of:\n  * invalid API key;\n  * invalid time window value;\n  * invalid HMAC signature format.\n"
      example:
        error:
          code: 1002
          message: Authorization is required or has been failed
  responses:
    wallet_Error:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/wallet_Error'
    wallet_504:
      description: Gateway Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/wallet_GatewayTimeout'
    wallet_429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/wallet_TooManyRequests'
    wallet_403:
      description: Forbidden
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/wallet_Forbidden'
            - $ref: '#/components/schemas/wallet_ShouldUpgradePermission'
            - $ref: '#/components/schemas/wallet_NotEnoughPermissions'
    wallet_401:
      description: Unauthorized
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/wallet_UnauthorizedBasic'
            - $ref: '#/components/schemas/wallet_UnauthorizedHS256'
            - $ref: '#/components/schemas/wallet_BadFormatHS256'
            - $ref: '#/components/schemas/wallet_AuthInvalid'
            - $ref: '#/components/schemas/wallet_BadFormat'
  parameters:
    wallet_Sort:
      name: sort
      in: query
      schema:
        type: string
        default: desc
        enum:
        - desc
        - asc
        - DESC
        - ASC
      description: "Sort order.\n\nValues:\n  * `asc`—ascending (from A to Z);\n  * `desc`—descending (from Z to A).\n"
    wallet_IdTill:
      name: id_till
      in: query
      schema:
        type: integer
        format: uint64
        example: 332274
      description: 'Transaction `id` end value (inclusive).

        '
    wallet_Limit:
      name: limit
      in: query
      schema:
        maximum: 1000
        minimum: 1
        type: integer
        format: int
        default: 100
      description: The number of items to return.
    wallet_Offset:
      name: offset
      in: query
      schema:
        maximum: 100000
        minimum: 0
        type: integer
        format: int
        default: 0
      description: The number of items to skip before starting to collect the result set.
    wallet_From:
      name: from
      in: query
      schema:
        type: string
        format: date-time
        description: 'Interval start value.


          Format: RFC 3339 in nanoseconds

          '
        example: 2024-03-22 15:04:05Z07:00
      description: 'Interval start value (inclusive).


        ℹ️ `order_by` defines the value type.

        '
    wallet_IdFrom:
      name: id_from
      in: query
      schema:
        type: integer
        format: uint64
        example: 221163
      description: 'Transaction `id` start value (inclusive).

        '
    wallet_Till:
      name: till
      in: query
      schema:
        type: string
        format: date-time
        description: 'Interval end value.


          Format: RFC 3339 in nanoseconds

          '
        example: 2024-03-22 15:04:05Z07:00
      description: 'Interval end value (inclusive).


        ℹ️ `order_by` defines the value type.

        '
  securitySchemes:
    wallet_BasicAuth:
      type: http
      description: Provide a public key as the username and a secret key as the password.
      scheme: basic
    wallet_BearerAuth:
      type: http
      description: Provide a bearer token obtained from the authentication service.
      scheme: bearer
      bearerFormat: JWT
    trading_BasicAuth:
      type: http
      description: Provide a public key as the username and a secret key as the password.
      scheme: basic
    trading_BearerAuth:
      type: http
      description: Provide a bearer token obtained from the authentication service.
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- hitbtc-api-v3-spec.yaml
- hitbtc-openapi.yml