> ## Documentation Index
> Fetch the complete documentation index at: https://learn.breezing.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Transactions API

> Retrieve Breezing transactions with filters, cursor pagination, and accounting fields for crypto accounting automation and review workflows.



## OpenAPI

````yaml GET /transactions
openapi: 3.1.0
info:
  title: Breezing Public API
  version: 1.0.0
  description: >-
    Crypto accounting API for programmatic access and AI agents. Authenticate
    with an API key using the Authorization header: `Bearer brz_...`
servers:
  - url: https://api.breezing.io/v1
security:
  - BearerAuth: []
paths:
  /transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      description: >-
        List crypto transactions with pagination and filters.


        Available filters: walletId, status, account, hasAccount, isSpam,
        isLocked, dateFrom, dateTo. There are no direction, token, or chain
        filters; use the response fields to filter client-side if needed.


        Each transaction includes:

        • Financial data: amount, fee, costBasis (read-only, computed by NGL
        calculation), amountFiat, feeFiat, net (read-only, net gain/loss),
        token, chain, direction (in/out).

        • Accounting fields: account (contra account, e.g. Sales, Legal),
        assetAccount, feeAssetAccount, status, type, note,
        accountingDescription, vat, isSpam, extraLabel.

        • Context fields: functionName (smart contract function called on-chain,
        read-only), isInternal (system-computed: true = transfer between the
        user's own wallets), exchangeId (system-set: non-null number = exchange
        trade), walletFromName/walletToName (contact names for counterparty
        addresses; different naming layer than wallet names in wallets_list).


        Default: 50 per page, newest first. Excludes spam and locked unless
        overridden.


        Tips for categorization:

        • Use walletFromName/walletToName to understand transaction context. For
        example, if walletToName is "Binance", the transaction is likely a
        deposit to an exchange.

        • Use "type" and "functionName" to understand what a transaction is.
        Note: type is a freeform label (not business logic). Values like
        "transaction" or "internal" are system-set during import but safe to
        overwrite.

        • If isInternal=true, the transaction is a transfer between the user's
        own wallets. Recommend using Breezing's Auto Apply Account feature.

        • If exchangeId is a non-null number, the transaction is an exchange
        trade. Also recommend Auto Apply Account.

        • Filter by hasAccount="false" to find uncategorized transactions.

        • For recurring patterns (same wallet, same counterparty), suggest the
        user create a Rule in Breezing to auto-categorize future transactions.
      parameters:
        - schema:
            type: string
            description: >-
              Organization ID. Use GET /v1/companies to discover available
              org/company pairs.
            example: '1'
          required: true
          description: >-
            Organization ID. Use GET /v1/companies to discover available
            org/company pairs.
          name: orgId
          in: query
        - schema:
            type: string
            description: >-
              Company ID. Use GET /v1/companies to discover available companies
              and their access levels.
            example: '1'
          required: true
          description: >-
            Company ID. Use GET /v1/companies to discover available companies
            and their access levels.
          name: companyId
          in: query
        - schema:
            type: string
            description: Filter by wallet ID. Use wallets_list to find IDs.
            example: '1'
          required: false
          description: Filter by wallet ID. Use wallets_list to find IDs.
          name: walletId
          in: query
        - schema:
            type: string
            enum:
              - notStarted
              - reviewRequired
              - reconciled
              - manuallyReconciled
              - paid
              - synced
            description: >-
              Filter by status. Use "notStarted" for uncategorized,
              "reviewRequired" for transactions flagged for client review,
              "reconciled" for categorized and verified.
          required: false
          description: >-
            Filter by status. Use "notStarted" for uncategorized,
            "reviewRequired" for transactions flagged for client review,
            "reconciled" for categorized and verified.
          name: status
          in: query
        - schema:
            type: string
            description: Filter by exact account code (e.g. "4100")
          required: false
          description: Filter by exact account code (e.g. "4100")
          name: account
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: >-
              Filter by whether a contra account is assigned. hasAccount="false"
              finds uncategorized transactions that still need an account.
          required: false
          description: >-
            Filter by whether a contra account is assigned. hasAccount="false"
            finds uncategorized transactions that still need an account.
          name: hasAccount
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
              - all
            default: 'false'
            description: >-
              Spam filter (default: "false"). Breezing auto-detects spam/airdrop
              tokens. Use "all" to include them, "true" to see only spam.
          required: false
          description: >-
            Spam filter (default: "false"). Breezing auto-detects spam/airdrop
            tokens. Use "all" to include them, "true" to see only spam.
          name: isSpam
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
              - all
            default: 'false'
            description: >-
              Lock filter (default: "false"). Locked transactions belong to a
              closed period and cannot be modified. Use "all" to include them.
          required: false
          description: >-
            Lock filter (default: "false"). Locked transactions belong to a
            closed period and cannot be modified. Use "all" to include them.
          name: isLocked
          in: query
        - schema:
            type: string
            description: Start of date range (unix timestamp in seconds)
            example: '1700000000'
          required: false
          description: Start of date range (unix timestamp in seconds)
          name: dateFrom
          in: query
        - schema:
            type: string
            description: End of date range (unix timestamp in seconds)
            example: '1710000000'
          required: false
          description: End of date range (unix timestamp in seconds)
          name: dateTo
          in: query
        - schema:
            type: string
            description: >-
              Transaction ID to start after (for cursor-based pagination). Omit
              for the first page.
            example: '12345'
          required: false
          description: >-
            Transaction ID to start after (for cursor-based pagination). Omit
            for the first page.
          name: cursor
          in: query
        - schema:
            type: string
            default: '50'
            description: Number of transactions to return (1-100)
            example: '50'
          required: false
          description: Number of transactions to return (1-100)
          name: limit
          in: query
        - schema:
            type: string
            enum:
              - date
            default: date
            description: Field to order results by
          required: false
          description: Field to order results by
          name: orderBy
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            description: Sort direction
          required: false
          description: Sort direction
          name: sort
          in: query
      responses:
        '200':
          description: Transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      cursor:
                        type: integer
                        nullable: true
                      hasMore:
                        type: boolean
                    required:
                      - limit
                      - cursor
                      - hasMore
                required:
                  - success
                  - data
                  - pagination
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '403':
          description: >-
            API key has no access to this company, has read-only access where
            write was required, or the company subscription is inactive
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                required:
                  - success
                  - error
      security:
        - BearerAuth: []
components:
  schemas:
    Transaction:
      type: object
      properties:
        id:
          type: number
          description: Transaction ID
          example: 1
        orgId:
          type: number
          description: Organization ID
        companyId:
          type: number
          description: Company ID
        walletId:
          type: number
          description: Wallet ID
        date:
          type: number
          description: Transaction date (unix timestamp ms)
          example: 1700000000000
        direction:
          type: string
          enum:
            - in
            - out
          description: 'Transaction direction: in, out'
          example: in
        type:
          type: string
          nullable: true
          description: >-
            Transaction type as a freeform label. System may set values like
            "transaction" or "internal" during import, but these are just
            labels. The isInternal boolean controls actual internal transfer
            logic. Safe to overwrite with any descriptive value.
        status:
          type: string
          nullable: true
          enum:
            - notStarted
            - reviewRequired
            - reconciled
            - manuallyReconciled
            - paid
            - synced
            - null
          description: >-
            Transaction status lifecycle: notStarted (new/uncategorized) →
            reviewRequired (flagged for client review) → reconciled (categorized
            and verified) → manuallyReconciled (manually confirmed) → paid
            (synced to accounting software)
          example: reviewRequired
        amount:
          type: string
          description: Token amount (string for precision)
          example: '1.5'
        amountFiat:
          type: string
          description: Fiat equivalent amount
          example: '3000.00'
        fee:
          type: string
          description: Fee in token
          example: '-0.001'
        feeFiat:
          type: string
          description: Fee in fiat
          example: '-2.00'
        net:
          type: string
          description: >-
            Net gain/loss in fiat currency. Computed by NGL calculation (not
            user-settable). Zero for internal transfers and skipNgl=true
            transactions.
          example: '2998.00'
        costBasis:
          type: string
          description: >-
            Cost basis in fiat (weighted average or FIFO depending on company
            setting). Computed and stored during NGL calculation. Read-only via
            API.
          example: '2900.00'
        token:
          type: string
          description: Token symbol
          example: ETH
        feeToken:
          type: string
          description: Fee token symbol
          example: ETH
        tokenAddress:
          type: string
          nullable: true
          description: Token contract address
        feeTokenAddress:
          type: string
          nullable: true
          description: Fee token contract address
        transactionId:
          type: string
          description: Blockchain transaction hash
        chain:
          type: string
          nullable: true
          description: Blockchain identifier
          example: eth
        account:
          type: string
          nullable: true
          description: >-
            Contra (income/expense) account code: what was this transaction for?
            Use numeric codes from the chart of accounts.
        assetAccount:
          type: string
          nullable: true
          description: >-
            Balance-sheet asset account. Present on all transactions regardless
            of balanceSheetSetup. Value "(auto)" means Breezing resolves it at
            sync time from token-level mappings (Token View) or rules. Can be
            overridden with a specific numeric account code.
        feeAssetAccount:
          type: string
          nullable: true
          description: >-
            Balance-sheet account for the fee portion. Same rules as
            assetAccount, present on all transactions. "(auto)" resolves at sync
            time.
        accountingDescription:
          type: string
          nullable: true
          description: >-
            Description that syncs as the journal entry description in
            Xero/QuickBooks/Bexio. Use for invoice references, vendor names, or
            transaction context.
        currency:
          type: string
          nullable: true
          description: Fiat currency (3 chars)
          example: USD
        walletFrom:
          type: string
          nullable: true
          description: Source wallet address
        walletTo:
          type: string
          nullable: true
          description: Destination wallet address
        walletFromId:
          type: number
          nullable: true
          description: Source wallet contact ID
        walletFromName:
          type: string
          nullable: true
          description: >-
            Name of the source address from the contacts table (counterparty
            naming). This is NOT the wallet name from wallets_list. It is the
            name assigned to the counterparty address. Different naming layer.
        walletToId:
          type: number
          nullable: true
          description: Destination wallet contact ID
        walletToName:
          type: string
          nullable: true
          description: >-
            Name of the destination address from the contacts table
            (counterparty naming). Same distinction as walletFromName: different
            naming layer than wallets_list.
        isInternal:
          type: boolean
          description: >-
            System-computed: true if Breezing detected this as a transfer
            between the user's own wallets (matched opposite-direction
            transactions on the same hash). Independent of the "type" field. A
            transaction can have isInternal=false with type="internal". Use Auto
            Apply Account for isInternal=true transactions.
        isSpam:
          type: boolean
          description: >-
            Whether this is flagged as spam. Breezing auto-detects many
            spam/airdrop tokens.
        isLocked:
          type: boolean
          description: >-
            Whether transaction is locked (closed period). Locked transactions
            cannot be modified.
        note:
          type: string
          nullable: true
          description: >-
            User note. Internal only, not synced to accounting software. Use
            accountingDescription for journal entry text.
        exchangeId:
          type: number
          nullable: true
          description: >-
            Exchange trade group ID (system-set). Non-null number means this is
            an exchange trade on a connected exchange. Use Auto Apply Account
            for these. Read-only.
        createdAt:
          type: number
          description: Created timestamp (unix ms)
        updatedAt:
          type: number
          description: Updated timestamp (unix ms)
        createdBy:
          type: number
          description: Created by user ID
        updatedBy:
          type: number
          description: Updated by user ID
        lastSync:
          type: number
          nullable: true
          description: Last sync timestamp (unix ms)
        addedVia:
          type: string
          nullable: true
          description: How the transaction was added
        extraLabel:
          type: string
          nullable: true
          description: >-
            Extra label: freeform text for custom tagging or grouping, visible
            in reports
        functionName:
          type: string
          nullable: true
          description: >-
            Smart contract function name. Helps identify what the transaction
            did on-chain
        internalId:
          type: number
          nullable: true
          description: >-
            ID of the paired transaction in an internal transfer group. Set by
            the system when it detects matching opposite-direction transactions
            on the same hash. Read-only.
        skipNgl:
          type: boolean
          description: >-
            When true, net gain/loss is zeroed out for this transaction. Set by
            system for internal/exchange merges, or manually by user to exclude
            from tax calculations.
        skipNglReason:
          type: string
          nullable: true
          description: >-
            Freeform explanation for why NGL was skipped (e.g. "Internal
            transfer", "Warranty replacement"). User-settable.
        vat:
          type: string
          nullable: true
          description: >-
            VAT or sales tax code (e.g. "Output 8.1% VAT"). Synced to journal
            entries in accounting software.
        qboClass:
          type: string
          nullable: true
          description: >-
            QuickBooks Online class ID set on the transaction. Syncs to the
            journal entry class in QuickBooks. Maps to an id from the company
            qboClasses list.
        xeroTrackingCategory:
          type: string
          nullable: true
          description: >-
            Xero tracking category option ID set on the transaction. Syncs to
            the journal entry tracking category in Xero. Maps to an id from the
            company xeroTrackingCategories list.
      required:
        - id
        - orgId
        - companyId
        - walletId
        - date
        - direction
        - type
        - status
        - amount
        - amountFiat
        - fee
        - feeFiat
        - net
        - costBasis
        - token
        - feeToken
        - tokenAddress
        - feeTokenAddress
        - transactionId
        - chain
        - account
        - assetAccount
        - feeAssetAccount
        - accountingDescription
        - currency
        - walletFrom
        - walletTo
        - walletFromId
        - walletFromName
        - walletToId
        - walletToName
        - isInternal
        - isSpam
        - isLocked
        - note
        - exchangeId
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
        - lastSync
        - addedVia
        - extraLabel
        - functionName
        - internalId
        - skipNgl
        - skipNglReason
        - vat
        - qboClass
        - xeroTrackingCategory

````