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

# Wallet History

> Get Bitcoin transaction history for a wallet. The wallet identifier accepts either a Bitcoin address or an xpub - when an xpub is supplied, history is aggregated across all derived addresses server-side.

**Supported chain family:** Bitcoin (native BTC transfers).

export const EndpointMeta = ({premium, cus, cusUnit, mainnetOnly}) => {
  const items = [];
  const planName = typeof premium === "string" ? premium : "Pro";
  if (premium) {
    items.push({
      icon: "\u26a0\ufe0f",
      label: "Premium endpoint",
      text: <>
          Requires the <strong>{planName} plan</strong> or above.{" "}
          <a href="/data-api/introduction/resources/premium-endpoints">
            View all
          </a>
          .
        </>
    });
  }
  if (cus) {
    const isDynamic = !!cusUnit;
    items.push({
      icon: "\u26a1",
      label: isDynamic ? "Dynamic cost" : "Endpoint cost",
      text: isDynamic ? <>
          {cus} CUs per {cusUnit}.{" "}
          <a href="/get-started/pricing#dynamic-endpoints">Learn more</a>.
        </> : <>
          {cus} CUs.{" "}
          <a href="/get-started/pricing">Learn more</a>.
        </>
    });
  }
  if (mainnetOnly) {
    items.push({
      icon: "\ud83d\udd17",
      label: "Mainnet only",
      text: <>Testnet chains are not supported.</>
    });
  }
  if (items.length === 0) return null;
  return <div className="endpoint-meta" style={{
    border: "1px solid var(--border-color, #e2e8f0)",
    borderRadius: "8px",
    overflow: "hidden",
    marginBottom: "16px",
    fontSize: "14px",
    lineHeight: "1.6",
    maxWidth: "100%"
  }}>
      <style dangerouslySetInnerHTML={{
    __html: `
            .endpoint-meta {
              --border-color: #e2e8f0;
              --row-bg: #f8fafc;
              --label-color: #0f172a;
              --text-color: #1f2937;
            }
            .endpoint-meta a {
              color: #0f7fff !important;
              text-decoration: underline;
            }
            @media (prefers-color-scheme: dark) {
              .endpoint-meta {
                --border-color: #374151 !important;
                --row-bg: #1e293b !important;
                --label-color: #f9fafb !important;
                --text-color: #e5e7eb !important;
              }
              .endpoint-meta a {
                color: #60a5fa !important;
              }
            }
            html.dark .endpoint-meta,
            [data-theme="dark"] .endpoint-meta {
              --border-color: #374151 !important;
              --row-bg: #1e293b !important;
              --label-color: #f9fafb !important;
              --text-color: #e5e7eb !important;
            }
            html.dark .endpoint-meta a,
            [data-theme="dark"] .endpoint-meta a {
              color: #60a5fa !important;
            }
          `
  }} />
      {items.map((item, i) => <div key={i} style={{
    display: "flex",
    alignItems: "baseline",
    gap: "8px",
    padding: "10px 14px",
    borderBottom: i < items.length - 1 ? "1px solid var(--border-color, #e2e8f0)" : "none",
    backgroundColor: "var(--row-bg, #f8fafc)"
  }}>
          <span style={{
    flexShrink: 0
  }}>{item.icon}</span>
          <span style={{
    wordBreak: "break-word",
    color: "var(--text-color, #1f2937)"
  }}>
            <strong style={{
    color: "var(--label-color, #0f172a)"
  }}>
              {item.label}:
            </strong>{" "}
            {item.text}
          </span>
        </div>)}
    </div>;
};

<EndpointMeta cus={150} cusUnit="chain" />

<Note>
  The `walletAddressOrPublicKey` path parameter accepts either a Bitcoin address or an **xpub** — when an xpub is supplied, history is aggregated across all derived addresses server-side.
</Note>

<Info>
  **Address auto-detection:** for a Bitcoin address or xpub, the `chains` parameter is optional — Moralis detects the chain family from the address format. Passing `chains=bitcoin` explicitly still works.
</Info>


## OpenAPI

````yaml /openapi-files/data-api/bitcoin-api-v1.json GET /v1/wallets/{walletAddressOrPublicKey}/history
openapi: 3.0.0
info:
  title: Moralis Bitcoin Data API
  description: >-
    Bitcoin-scoped view of the Moralis Universal API. Every endpoint below is a
    Universal endpoint with chain inputs restricted to Bitcoin for clarity.
  version: '1.0'
servers:
  - url: https://api.moralis.com
security: []
externalDocs:
  description: Moralis API Docs
  url: https://docs.moralis.com
paths:
  /v1/wallets/{walletAddressOrPublicKey}/history:
    get:
      tags:
        - Wallets
      summary: Get Bitcoin wallet transaction history
      description: >-
        Get Bitcoin transaction history for a wallet. The wallet identifier
        accepts either a Bitcoin address or an xpub - when an xpub is supplied,
        history is aggregated across all derived addresses server-side.


        **Supported chain family:** Bitcoin (native BTC transfers).
      operationId: getWalletHistory
      parameters:
        - name: walletAddressOrPublicKey
          required: true
          in: path
          description: >-
            A Bitcoin address or an xpub. When an xpub is supplied, the API
            derives all addresses server-side.
          examples:
            bitcoinAddress:
              value: bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq
            bitcoinXpub:
              value: >-
                xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKrhko4egpiMZbpiaQL2jkwSB1icqYh2cfDfVxdx4df189oLKnC5fSwqPfgyP3hooxujYzAu3fDVmz
          schema:
            type: string
        - name: chains
          required: false
          in: query
          description: Chains to query. For the Bitcoin API, pass `bitcoin`.
          schema:
            type: array
            items:
              type: string
              enum:
                - bitcoin
        - name: limit
          required: false
          in: query
          description: The limit per page
          schema:
            minimum: 1
            maximum: 100
            default: 100
            type: number
        - name: cursor
          required: false
          in: query
          description: The cursor to the next page
          schema:
            type: string
        - name: order
          required: false
          in: query
          description: The order of items
          schema:
            default: DESC
            enum:
              - ASC
              - DESC
            type: string
        - name: fromDate
          required: false
          in: query
          description: >-
            The start date from which to get the wallet history (format in
            seconds or string accepted by momentjs)

            * Provide the param 'fromBlock' or 'fromDate'

            * If 'fromDate' and 'fromBlock' are provided, 'fromBlock' will be
            used.
          schema:
            type: string
        - name: toDate
          required: false
          in: query
          description: >-
            The end date from which to get the wallet history (format in seconds
            or string accepted by momentjs)

            * Provide the param 'toBlock' or 'toDate'

            * If 'toDate' and 'toBlock' are provided, 'toBlock' will be used.
          schema:
            type: string
        - name: fromBlock
          required: false
          in: query
          description: >-
            The minimum block number from which to get the wallet history

            * Provide the param 'fromBlock' or 'fromDate'

            * If 'fromDate' and 'fromBlock' are provided, 'fromBlock' will be
            used.
          schema:
            type: number
        - name: toBlock
          required: false
          in: query
          description: The block number to get the wallet history until
          schema:
            type: number
        - name: verbose
          required: false
          in: query
          description: >-
            When true, returns full raw chain-specific data including logs,
            input data, and vin/vout arrays. Array fields are capped at 100
            items with a hasMore flag.
          schema:
            default: false
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWalletHistoryResponseDto'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    GetWalletHistoryResponseDto:
      type: object
      properties:
        address:
          type: string
          description: The queried wallet address
          example: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
        addressType:
          type: string
          description: The wallet address type
          enum:
            - bitcoin
          example: evm
        cursor:
          type: string
          description: Opaque cursor token for pagination (null when no more pages)
          nullable: true
        page:
          type: number
          description: Current page number (1-indexed)
          example: 1
        pageSize:
          type: number
          description: Number of items in this page
        result:
          description: Array of wallet history items
          type: array
          items:
            $ref: '#/components/schemas/WalletHistoryItemDto'
        meta:
          description: Response metadata with sync status and diagnostics
          allOf:
            - $ref: '#/components/schemas/WalletHistoryMetaDto'
      required:
        - address
        - addressType
        - cursor
        - page
        - pageSize
        - result
        - meta
    WalletHistoryItemDto:
      type: object
      properties:
        chainId:
          type: string
          description: Chain ID (e.g. "bitcoin")
          example: bitcoin
        block:
          description: Block information
          allOf:
            - $ref: '#/components/schemas/WalletHistoryBlockDto'
        transaction:
          description: Transaction information with transfers and enrichment
          allOf:
            - $ref: '#/components/schemas/WalletHistoryTransactionDto'
        raw:
          description: Bitcoin raw transaction data
          type: object
          properties:
            bitcoin:
              $ref: '#/components/schemas/WalletHistoryBitcoinRawDto'
          required:
            - bitcoin
        meta:
          type: object
          description: Extensible metadata placeholder (Universal API convention)
          example: {}
      required:
        - chainId
        - block
        - transaction
        - raw
        - meta
    WalletHistoryMetaDto:
      type: object
      properties:
        syncedAt:
          type: object
          description: >-
            Per-chain indexed block height (-1 while real sync metadata is
            unavailable)
          example:
            bitcoin: latest
        unsupportedChains:
          description: >-
            Chain IDs that were requested but are not supported (null when all
            chains supported)
          nullable: true
          type: array
          items:
            type: string
        failedChains:
          description: Chain IDs where fetching failed (null when no failures occurred)
          nullable: true
          type: array
          items:
            type: string
        missingTransactions:
          type: object
          description: >-
            Per-chain count of transactions that could not be enriched (null
            when none missing)
          nullable: true
          example: null
      required:
        - syncedAt
        - unsupportedChains
        - failedChains
        - missingTransactions
    WalletHistoryBlockDto:
      type: object
      properties:
        number:
          type: number
          description: Block number
        timestamp:
          type: string
          description: Block timestamp (ISO 8601)
        hash:
          type: string
          description: Block hash
      required:
        - number
        - timestamp
        - hash
    WalletHistoryTransactionDto:
      type: object
      properties:
        hash:
          type: string
          description: Transaction hash
        index:
          type: number
          description: Transaction index within the block
          nullable: true
        status:
          type: string
          description: Transaction status
          nullable: true
        direction:
          type: string
          description: Transaction direction relative to the queried wallet
          enum:
            - incoming
            - outgoing
            - self
          nullable: true
        category:
          type: string
          description: Transaction category
          nullable: true
        summary:
          type: string
          description: Human-readable transaction summary
          nullable: true
        methodLabel:
          type: string
          description: Decoded method label from ABI
          nullable: true
        possibleSpam:
          type: boolean
          description: Whether the transaction is likely spam
          nullable: true
        initiatedBy:
          description: >-
            Address that initiated the transaction (null at tx level on
            FullTransactionResponse)
          nullable: true
          allOf:
            - $ref: '#/components/schemas/AddressParticipantDto'
        from:
          description: Transaction sender
          allOf:
            - $ref: '#/components/schemas/AddressParticipantDto'
        to:
          description: Transaction recipient (null for contract creation transactions)
          nullable: true
          allOf:
            - $ref: '#/components/schemas/AddressParticipantDto'
        fee:
          description: Transaction fee
          nullable: true
          allOf:
            - $ref: '#/components/schemas/TransactionFeeDto'
        confirmations:
          type: number
          description: Number of block confirmations
          nullable: true
        nativeTransfers:
          type: object
          description: Native currency transfers in this transaction
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/NativeTransferDto'
            hasMore:
              type: boolean
        tokenTransfers:
          type: object
          description: Token transfers
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/TokenTransferDto'
            hasMore:
              type: boolean
        nftTransfers:
          type: object
          description: NFT transfers in this transaction
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/NftTransferDto'
            hasMore:
              type: boolean
      required:
        - hash
        - index
        - status
        - direction
        - category
        - summary
        - methodLabel
        - possibleSpam
        - initiatedBy
        - from
        - to
        - fee
        - confirmations
        - nativeTransfers
        - tokenTransfers
        - nftTransfers
    WalletHistoryBitcoinRawDto:
      type: object
      properties:
        version:
          type: number
          nullable: true
          description: Transaction version
        size:
          type: number
          description: Transaction size in bytes
          nullable: true
        vsize:
          type: number
          description: Virtual size in weight units / 4 (SegWit)
          nullable: true
        coinbase:
          type: boolean
          description: Whether this is a coinbase transaction
        rbf:
          type: boolean
          description: >-
            Whether the transaction signals replace-by-fee (any vin sequence <
            0xFFFFFFFE)
        inputCount:
          type: number
          description: Number of transaction inputs
        outputCount:
          type: number
          description: Number of transaction outputs
        vin:
          type: array
          description: Transaction inputs (verbose only)
          nullable: true
          items:
            type: object
            properties:
              txid:
                type: string
                nullable: true
              vout:
                type: number
                nullable: true
              sequence:
                type: number
                nullable: true
              addresses:
                type: array
                items:
                  type: string
                nullable: true
              value:
                type: string
                nullable: true
              isOwn:
                type: boolean
                nullable: true
        vout:
          type: array
          description: Transaction outputs (verbose only)
          nullable: true
          items:
            type: object
            properties:
              'n':
                type: number
              addresses:
                type: array
                items:
                  type: string
                nullable: true
              value:
                type: string
              hex:
                type: string
                nullable: true
              spent:
                type: boolean
                nullable: true
              isOwn:
                type: boolean
                nullable: true
      required:
        - version
        - size
        - vsize
        - coinbase
        - rbf
        - inputCount
        - outputCount
        - vin
        - vout
    AddressParticipantDto:
      type: object
      properties:
        address:
          type: string
          description: Wallet or contract address
        addressLabel:
          type: string
          description: Human-readable label for the address
          nullable: true
        entity:
          description: Entity information associated with the address
          nullable: true
          allOf:
            - $ref: '#/components/schemas/AddressEntityDto'
      required:
        - address
        - addressLabel
        - entity
    TransactionFeeDto:
      type: object
      properties:
        amount:
          type: string
          description: Fee amount formatted to native decimals
        amountRaw:
          type: string
          description: Raw fee in smallest unit (wei/satoshi)
      required:
        - amount
        - amountRaw
    NativeTransferDto:
      type: object
      properties:
        fromAddress:
          type: string
          description: Sender address
        toAddress:
          type: string
          description: Recipient address
        amount:
          type: string
          description: Amount transferred in native currency
        direction:
          type: string
          description: Transfer direction relative to the queried wallet
          enum:
            - incoming
            - outgoing
            - self
          nullable: true
        isInternal:
          type: boolean
          description: Whether this is an internal (trace-level) transfer
      required:
        - fromAddress
        - toAddress
        - amount
        - direction
        - isInternal
    TokenTransferDto:
      type: object
      properties:
        fromAddress:
          type: string
          description: Sender address
        toAddress:
          type: string
          description: Recipient address
        value:
          type: string
          description: Transfer value (raw, in token smallest unit)
        direction:
          type: string
          description: Transfer direction relative to the queried wallet
          enum:
            - incoming
            - outgoing
            - self
          nullable: true
        tokenAddress:
          type: string
          description: Token contract address
        tokenSymbol:
          type: string
          description: Token symbol
          nullable: true
        tokenName:
          type: string
          description: Token name
          nullable: true
        tokenDecimals:
          type: number
          description: Token decimals
          nullable: true
        tokenLogo:
          type: string
          description: Token logo URL
          nullable: true
      required:
        - fromAddress
        - toAddress
        - value
        - direction
        - tokenAddress
        - tokenSymbol
        - tokenName
        - tokenDecimals
        - tokenLogo
    NftTransferDto:
      type: object
      properties:
        fromAddress:
          type: string
          description: Sender address
        toAddress:
          type: string
          description: Recipient address
        tokenAddress:
          type: string
          description: NFT contract address
        tokenId:
          type: string
          description: Token ID
        amount:
          type: string
          description: Amount transferred (1 for ERC721)
        direction:
          type: string
          description: Transfer direction relative to the queried wallet
          enum:
            - incoming
            - outgoing
            - self
          nullable: true
        tokenType:
          type: string
          description: Token type (ERC721, ERC1155)
      required:
        - fromAddress
        - toAddress
        - tokenAddress
        - tokenId
        - amount
        - direction
        - tokenType
    AddressEntityDto:
      type: object
      properties:
        id:
          type: string
          description: Entity ID
        name:
          type: string
          description: Entity name
        logo:
          type: string
          description: Entity logo URL
      required:
        - id
        - name
        - logo
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

````