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

# Get Portfolio Transactions

> Get a detailed history of all transactions in your portfolio

<Note>**4** credits per request</Note><hr />

<AccordionGroup>
  <Accordion title="You will get">
    * Complete list of buy/sell operations
    * Transaction dates and amounts
    * Price information at time of transaction
    * Supports pagination for viewing large transaction sets
  </Accordion>

  <Accordion title="Required">
    <Note>This endpoint is only available for users with a Degen plan subscription (when using shareToken).</Note>

    * shareToken OR portfolioId: Provide one of these to identify the portfolio.
      * shareToken: Get this from your CoinStats portfolio page by clicking "Share"
      * portfolioId: Use a portfolio connected via POST /portfolio/wallet or POST /portfolio/exchange
    * If neither is provided, returns transactions from all API-connected portfolios
    * currency: Specify the currency for price values
  </Accordion>

  <Accordion title="Optional">
    * page & limit: Control the number of transactions per page
    * from & to: Filter transactions by date range
    * passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter)
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml /api-reference/openapi.json get /v1/portfolio/transactions
openapi: 3.0.0
info:
  title: CoinStats Public API
  description: >-
    CoinStats Public API — programmatic access to market data, news, NFTs,
    wallets, exchange connections, and user portfolios. Authenticate every
    request with the `X-API-KEY` header (or an OAuth Bearer token in the
    `Authorization` header). Generate keys at https://openapi.coinstats.app.
  version: '1.0'
  contact: {}
servers:
  - url: https://openapiv1.coinstats.app
security: []
tags:
  - name: CoinStats
    description: ''
  - name: Market Data
    description: >-
      The Market Data section of the API provides endpoints to access a wide
      range of market-related information, including cryptocurrency coins,
      ticker data, and fiat currency rates. This category offers comprehensive
      data to help users monitor and analyze the cryptocurrency market, track
      prices, and gain insights into market trends
  - name: News
    description: >-
      The News section of the API allows you to access news articles and updates
      related to cryptocurrencies and the blockchain industry. It provides
      valuable information from various sources to keep you informed about the
      latest developments
  - name: NFTs
    description: >-
      The NFT section of the API provides endpoints to interact with
      Non-Fungible Tokens (NFTs), which are unique digital assets stored on a
      blockchain. These endpoints allow you to retrieve information about NFTs,
      including collections, assets, trending NFTs, and specific assets
      associated with wallet addresses.
  - name: Wallet Data
    description: >-
      The Wallet section of the API provides a comprehensive set of endpoints to
      manage and interact with wallets. It enables users to retrieve wallet
      balances, monitor syncing status, fetch transaction data, and synchronize
      wallet information with the blockchain. By integrating these endpoints
      into your application, you can offer robust wallet functionality to your
      users.
  - name: Exchange Connection
    description: >-
      The Exchange Connection section of the API provides a comprehensive set of
      endpoints to manage and interact with exchanges. It enables users to
      retrieve exchange balances, monitor syncing status, fetch transaction
      data. By integrating these endpoints into your application, you can offer
      robust exchange portfolio tracking functionality to your users.
  - name: User Portfolio
    description: >-
      The Portfolio section of the API provides a comprehensive set of endpoints
      to manage and interact with Share Portfolios. It enables users to retrieve
      current Portfolio Coins and Transactions.
  - name: Usage
    description: The Usage section provides account-level API usage data.
  - name: Status
    description: The Status section provides API availability checks.
paths:
  /v1/portfolio/transactions:
    get:
      tags:
        - User Portfolio
      summary: Get a detailed history of all transactions in your portfolio
      operationId: get-portfolio-transactions
      parameters:
        - name: sharetoken
          required: false
          in: header
          description: '[Get Share Token](/sharetoken)'
          schema:
            type: string
        - name: passcode
          required: false
          in: header
          description: Passcode for accessing protected portfolio data
          schema:
            example: '123456'
            type: string
        - name: page
          required: false
          in: query
          description: Page number to retrieve (1-based indexing)
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items to return per page
          schema:
            example: 20
            type: number
        - name: currency
          required: true
          in: query
          description: The fiat currency to return values in
          schema:
            example: USD
            type: string
        - name: coinId
          required: false
          in: query
          description: Coin ID to filter transactions for a specific coin
          schema:
            example: bitcoin
            type: string
        - name: portfolioId
          required: false
          in: query
          description: >-
            Portfolio ID for accessing a specific API-connected portfolio.
            Required if shareToken is not provided.
          schema:
            example: abc123def456
            type: string
      responses:
        '200':
          description: Transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionItemResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                statusCode: 400
                message: Bad Request
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                statusCode: 403
                message: Forbidden
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '404':
          description: Not Found
          content:
            application/json:
              example:
                statusCode: 404
                message: Not Found
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '409':
          description: Conflict (for some endpoints)
          content:
            application/json:
              example:
                statusCode: 409
                message: Transactions not synced
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                statusCode: 429
                message: Rate limit exceeded
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '503':
          description: Service Unavailable
          content:
            application/json:
              example:
                statusCode: 503
                message: Service Unavailable. Please Contact Support
      security:
        - X-API-KEY: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request GET \
              --url 'https://openapiv1.coinstats.app/v1/portfolio/transactions?currency=USD' \
              --header 'X-API-KEY: <api-key>'
        - lang: python
          label: Python
          source: >-
            import requests


            url =
            "https://openapiv1.coinstats.app/v1/portfolio/transactions?currency=USD"


            headers = {"X-API-KEY": "<api-key>"}


            response = requests.request("GET", url, headers=headers)


            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const options = {method: 'GET', headers: {'X-API-KEY':
            '<api-key>'}};


            fetch('https://openapiv1.coinstats.app/v1/portfolio/transactions?currency=USD',
            options)
              .then((response) => response.json())
              .then((response) => console.log(response))
              .catch((err) => console.error(err));
        - lang: php
          label: PHP
          source: |-
            <?php

            $curl = curl_init();

            curl_setopt_array($curl, [
              CURLOPT_URL => "https://openapiv1.coinstats.app/v1/portfolio/transactions?currency=USD",
              CURLOPT_RETURNTRANSFER => true,
              CURLOPT_CUSTOMREQUEST => "GET",
              CURLOPT_HTTPHEADER => [
                "X-API-KEY: <api-key>"
              ],
            ]);

            $response = curl_exec($curl);
            $err = curl_error($curl);

            curl_close($curl);

            if ($err) {
              echo "cURL Error #:" . $err;
            } else {
              echo $response;
            }
        - lang: go
          label: Go
          source: "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\n\turl := \"https://openapiv1.coinstats.app/v1/portfolio/transactions?currency=USD\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\treq.Header.Add(\"X-API-KEY\", \"<api-key>\")\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := io.ReadAll(res.Body)\n\n\tfmt.Println(string(body))\n}"
        - lang: java
          label: Java
          source: >-
            HttpResponse<String> response =
            Unirest.get("https://openapiv1.coinstats.app/v1/portfolio/transactions?currency=USD")
              .header("X-API-KEY", "<api-key>")
              .asString();
components:
  schemas:
    TransactionItemResponseDto:
      type: object
      properties:
        data:
          description: Array of transaction items
          type: array
          items:
            $ref: '#/components/schemas/TransactionItemDto'
        meta:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PageMetaSimpleDto'
      required:
        - data
        - meta
    TransactionItemDto:
      type: object
      properties:
        transactionType:
          type: string
          description: Type of transaction performed
          example: Roll In
          enum:
            - Sent
            - Dust Convert
            - Roll In
            - Received
            - Swap
            - Buy
            - Sell
        date:
          type: string
          description: ISO 8601 timestamp of when the transaction occurred
          example: '2025-08-28T08:35:50.384Z'
        coinData:
          description: >-
            Main coin data for the transaction (optional for some transaction
            types)
          allOf:
            - $ref: '#/components/schemas/CoinDataDto'
        profitLoss:
          description: Profit and loss information for the transaction
          allOf:
            - $ref: '#/components/schemas/ProfitLossDto'
        fee:
          description: Transaction fee information
          allOf:
            - $ref: '#/components/schemas/FeeDto'
        transfers:
          description: >-
            List of transfers involved in the transaction (e.g., coins
            received/sent)
          type: array
          items:
            $ref: '#/components/schemas/TransferDto'
        portfolioInfo:
          description: Information about the portfolio where the transaction occurred
          allOf:
            - $ref: '#/components/schemas/PortfolioInfoDto'
        note:
          description: Transaction Notes
          allOf:
            - $ref: '#/components/schemas/PortfolioInfoDto'
      required:
        - transactionType
        - date
        - profitLoss
        - fee
        - portfolioInfo
    PageMetaSimpleDto:
      type: object
      properties:
        page:
          type: number
          description: The current page number
          example: 1
        limit:
          type: number
          description: The number of items per page
          example: 10
      required:
        - page
        - limit
    CoinDataDto:
      type: object
      properties:
        identifier:
          type: string
          description: Unique identifier for the coin in the transaction
          example: pepe
        count:
          type: number
          description: Amount of coins involved in the transaction (can be negative)
          example: 596062
        symbol:
          type: string
          description: Trading symbol of the coin
          example: PEPE
        totalWorth:
          type: number
          description: Total worth of the coins at transaction time in USD
          example: 6.06791116
        currentValue:
          type: number
          description: Current market value of the coins in USD
          example: 5.851540654
      required:
        - identifier
        - count
        - symbol
        - totalWorth
        - currentValue
    ProfitLossDto:
      type: object
      properties:
        profit:
          type: number
          description: >-
            Profit or loss amount in USD (positive for profit, negative for
            loss)
          example: -0.21637050600000052
        profitPercent:
          type: number
          description: Profit or loss percentage (positive for profit, negative for loss)
          example: -3.5658153241650377
        currentValue:
          type: number
          description: Current market value of the position in USD
          example: 5.851540654
      required:
        - profit
        - profitPercent
        - currentValue
    FeeDto:
      type: object
      properties:
        coin:
          description: Information about the coin used for transaction fees
          allOf:
            - $ref: '#/components/schemas/CoinDto'
        count:
          type: number
          description: Amount of fee paid
          example: 0.001
        toAddress:
          type: string
          description: Destination address for the fee transaction
          example: '0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f'
        fromAddress:
          type: string
          description: Source address for the fee transaction
          example: '0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e'
        totalWorth:
          type: number
          description: Total worth of the fee in USD
          example: 25.5
        price:
          type: number
          description: Price per unit of the fee coin in USD
          example: 25500
      required:
        - coin
        - count
        - totalWorth
        - price
    TransferDto:
      type: object
      properties:
        transferType:
          type: string
          description: Type of transfer operation
          example: Received
          enum:
            - Received
            - Sent
        items:
          description: List of items involved in the transfer
          type: array
          items:
            $ref: '#/components/schemas/TransferItemDto'
      required:
        - transferType
        - items
    PortfolioInfoDto:
      type: object
      properties:
        name:
          type: string
          description: Name of the portfolio or exchange where the transaction occurred
          example: KuCoin Spot
        icon:
          type: string
          description: URL to the portfolio or exchange icon
          example: https://static.coinstats.app/portfolio_images/kucoin_dark.png
      required:
        - name
        - icon
    CoinDto:
      type: object
      properties:
        rank:
          type: number
          example: 2
          description: Market rank of the coin
        identifier:
          type: string
          example: ethereum
          description: Unique identifier for the coin
        symbol:
          type: string
          example: ETH
          description: Trading symbol of the coin
        name:
          type: string
          description: Full name of the coin
          example: Ethereum
        icon:
          type: string
          example: https://static.coinstats.app/coins/1650455629727.png
          description: URL to the coin icon image
        isFake:
          type: boolean
          example: false
          description: Whether the coin is identified as fake
        isFiat:
          type: boolean
          example: false
          description: Whether the coin is a fiat currency
        priceChange24h:
          type: number
          example: -5.74
          description: Price change percentage in the last 24 hours
        priceChange1h:
          type: number
          example: 0.1
          description: Price change percentage in the last 1 hour
        priceChange7d:
          type: number
          example: 1.12
          description: Price change percentage in the last 7 days
        priceChange1m:
          type: number
          example: 8.42
          description: Price change percentage in the last 1 month
        volume:
          type: number
          example: 61315198931.43572
          description: Trading volume in the last 24 hours (USD)
      required:
        - rank
        - identifier
        - symbol
        - name
        - icon
        - priceChange24h
        - priceChange1h
        - priceChange7d
        - priceChange1m
        - volume
    TransferItemDto:
      type: object
      properties:
        coin:
          description: Information about the coin being transferred
          allOf:
            - $ref: '#/components/schemas/CoinDto'
        count:
          type: number
          description: Amount of coins transferred (can be negative for outgoing transfers)
          example: -0.00000544
        toAddress:
          type: string
          description: Destination wallet address
          example: '0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f'
        fromAddress:
          type: string
          description: Source wallet address
          example: '0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e'
        totalWorth:
          type: number
          description: Total worth of the transferred amount in USD
          example: 0.0000054389555199999995
        price:
          type: number
          description: Price per unit of the coin in USD at the time of transfer
          example: 0.999808
      required:
        - coin
  securitySchemes:
    X-API-KEY:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key required to access the endpoints. Generate one from your
        dashboard at https://openapi.coinstats.app and pass it in the
        `X-API-KEY` request header. Never expose your key in client-side code.

````