Add Portfolio Transaction

Add a new transaction to your manual portfolio

curl --request POST \
  --url https://openapiv1.coinstats.app/portfolio/transaction \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "coinId": "bitcoin",
  "count": 0.1,
  "date": 1715948176654,
  "price": 66252.93,
  "portfolioId": "xobgM6CHi1zaEJaCXmPWenVoS",
  "currency": "USD",
  "notes": "Some notes."
}
'

{
  "transactionType": "Roll In",
  "date": "2025-08-28T08:35:50.384Z",
  "profitLoss": {
    "profit": -0.21637050600000052,
    "profitPercent": -3.5658153241650377,
    "currentValue": 5.851540654
  },
  "fee": {
    "coin": {
      "rank": 2,
      "identifier": "ethereum",
      "symbol": "ETH",
      "name": "Ethereum",
      "icon": "https://static.coinstats.app/coins/1650455629727.png",
      "priceChange24h": -5.74,
      "priceChange1h": 0.1,
      "priceChange7d": 1.12,
      "volume": 61315198931.43572,
      "isFake": false,
      "isFiat": false
    },
    "count": 0.001,
    "totalWorth": 25.5,
    "price": 25500,
    "toAddress": "0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f",
    "fromAddress": "0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e"
  },
  "portfolioInfo": {
    "name": "KuCoin Spot",
    "icon": "https://static.coinstats.app/portfolio_images/kucoin_dark.png"
  },
  "coinData": {
    "identifier": "pepe",
    "count": 596062,
    "symbol": "PEPE",
    "totalWorth": 6.06791116,
    "currentValue": 5.851540654
  },
  "transfers": [
    {
      "transferType": "Received",
      "items": [
        {
          "coin": {
            "rank": 2,
            "identifier": "ethereum",
            "symbol": "ETH",
            "name": "Ethereum",
            "icon": "https://static.coinstats.app/coins/1650455629727.png",
            "priceChange24h": -5.74,
            "priceChange1h": 0.1,
            "priceChange7d": 1.12,
            "volume": 61315198931.43572,
            "isFake": false,
            "isFiat": false
          },
          "count": -0.00000544,
          "toAddress": "0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f",
          "fromAddress": "0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e",
          "totalWorth": 0.0000054389555199999995,
          "price": 0.999808
        }
      ]
    }
  ]
}

POST

portfolio

transaction

Add a new transaction to your manual portfolio

curl --request POST \
  --url https://openapiv1.coinstats.app/portfolio/transaction \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "coinId": "bitcoin",
  "count": 0.1,
  "date": 1715948176654,
  "price": 66252.93,
  "portfolioId": "xobgM6CHi1zaEJaCXmPWenVoS",
  "currency": "USD",
  "notes": "Some notes."
}
'

{
  "transactionType": "Roll In",
  "date": "2025-08-28T08:35:50.384Z",
  "profitLoss": {
    "profit": -0.21637050600000052,
    "profitPercent": -3.5658153241650377,
    "currentValue": 5.851540654
  },
  "fee": {
    "coin": {
      "rank": 2,
      "identifier": "ethereum",
      "symbol": "ETH",
      "name": "Ethereum",
      "icon": "https://static.coinstats.app/coins/1650455629727.png",
      "priceChange24h": -5.74,
      "priceChange1h": 0.1,
      "priceChange7d": 1.12,
      "volume": 61315198931.43572,
      "isFake": false,
      "isFiat": false
    },
    "count": 0.001,
    "totalWorth": 25.5,
    "price": 25500,
    "toAddress": "0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f",
    "fromAddress": "0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e"
  },
  "portfolioInfo": {
    "name": "KuCoin Spot",
    "icon": "https://static.coinstats.app/portfolio_images/kucoin_dark.png"
  },
  "coinData": {
    "identifier": "pepe",
    "count": 596062,
    "symbol": "PEPE",
    "totalWorth": 6.06791116,
    "currentValue": 5.851540654
  },
  "transfers": [
    {
      "transferType": "Received",
      "items": [
        {
          "coin": {
            "rank": 2,
            "identifier": "ethereum",
            "symbol": "ETH",
            "name": "Ethereum",
            "icon": "https://static.coinstats.app/coins/1650455629727.png",
            "priceChange24h": -5.74,
            "priceChange1h": 0.1,
            "priceChange7d": 1.12,
            "volume": 61315198931.43572,
            "isFake": false,
            "isFiat": false
          },
          "count": -0.00000544,
          "toAddress": "0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f",
          "fromAddress": "0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e",
          "totalWorth": 0.0000054389555199999995,
          "price": 0.999808
        }
      ]
    }
  ]
}

4 credits per request

You will get

Support for buy, sell, and transfer operations
Automatically updates your portfolio holdings
Validates transaction data before recording
Returns the details of the created transaction

Required

This endpoint is only available for users with a Degen plan subscription.

shareToken: Get this from your CoinStats portfolio page
Transaction details in request body:
- coinId: The cryptocurrency’s identifier
- count: Amount (negative for sells)
- date: Transaction timestamp (optional)
- price: Price at time of transaction (optional)

Optional

notes: Add personal notes to the transaction
currency: Specify currency for price (default: USD)
passcode: Passcode for accessing protected portfolio data (can be passed in header or query parameter)

Authorizations

X-API-KEY

string

header

required

API key needed to access the endpoints. Example: 'demo-api-key'

Headers

passcode

string

Passcode for accessing protected portfolio data

Example:

"123456"

Query Parameters

Get Share Token

passcode

string

Passcode for accessing protected portfolio data

Example:

"123456"

Body

application/json

coinId

string

required

Coin ID from CoinStats API. For fiats you can send coin ID like this: FiatCoinUSD.

Example:

"bitcoin"

count

number

required

Amount of coin. For sell transactions, this should be negative.

Example:

0.1

date

number

Transaction date in milliseconds. If not provided, current date will be used.

Example:

1715948176654

price

number

Price of coin in USD at the time of transaction.

Example:

66252.93

portfolioId

string

If shared portfolio is not manual portfolio, then this field is required.

Example:

"xobgM6CHi1zaEJaCXmPWenVoS"

currency

string

Default is USD.

Example:

"USD"

notes

string

Transaction notes.

Example:

"Some notes."

Response

PortfolioTransactions

transactionType

enum<string>

required

Type of transaction performed

Available options:

Sent,

Dust Convert,

Roll In,

Received,

Swap,

Buy,

Sell

Example:

"Roll In"

date

string

required

ISO 8601 timestamp of when the transaction occurred

Example:

"2025-08-28T08:35:50.384Z"

profitLoss

object

required

Profit and loss information for the transaction

Show child attributes

profitLoss.profit

number

required

Profit or loss amount in USD (positive for profit, negative for loss)

Example:

-0.21637050600000052

profitLoss.profitPercent

number

required

Profit or loss percentage (positive for profit, negative for loss)

Example:

-3.5658153241650377

profitLoss.currentValue

number

required

Current market value of the position in USD

Example:

5.851540654

fee

object

required

Transaction fee information

Show child attributes

fee.coin

object

required

Information about the coin used for transaction fees

Show child attributes

fee.coin.rank

number

required

Market rank of the coin

Example:

2

fee.coin.identifier

string

required

Unique identifier for the coin

Example:

"ethereum"

fee.coin.symbol

string

required

Trading symbol of the coin

Example:

"ETH"

fee.coin.name

string

required

Full name of the coin

Example:

"Ethereum"

fee.coin.icon

string

required

URL to the coin icon image

Example:

"https://static.coinstats.app/coins/1650455629727.png"

fee.coin.priceChange24h

number

required

Price change percentage in the last 24 hours

Example:

-5.74

fee.coin.priceChange1h

number

required

Price change percentage in the last 1 hour

Example:

0.1

fee.coin.priceChange7d

number

required

Price change percentage in the last 7 days

Example:

1.12

fee.coin.volume

number

required

Trading volume in the last 24 hours (USD)

Example:

61315198931.43572

fee.coin.isFake

boolean

Whether the coin is identified as fake

Example:

false

fee.coin.isFiat

boolean

Whether the coin is a fiat currency

Example:

false

fee.count

number

required

Amount of fee paid

Example:

0.001

fee.totalWorth

number

required

Total worth of the fee in USD

Example:

25.5

fee.price

number

required

Price per unit of the fee coin in USD

Example:

25500

fee.toAddress

string

Destination address for the fee transaction

Example:

"0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f"

fee.fromAddress

string

Source address for the fee transaction

Example:

"0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e"

portfolioInfo

object

required

Information about the portfolio where the transaction occurred

Show child attributes

portfolioInfo.name

string

required

Name of the portfolio or exchange where the transaction occurred

Example:

"KuCoin Spot"

portfolioInfo.icon

string

required

URL to the portfolio or exchange icon

Example:

"https://static.coinstats.app/portfolio_images/kucoin_dark.png"

coinData

object

Main coin data for the transaction (optional for some transaction types)

Show child attributes

coinData.identifier

string

required

Unique identifier for the coin in the transaction

Example:

"pepe"

coinData.count

number

required

Amount of coins involved in the transaction (can be negative)

Example:

596062

coinData.symbol

string

required

Trading symbol of the coin

Example:

"PEPE"

coinData.totalWorth

number

required

Total worth of the coins at transaction time in USD

Example:

6.06791116

coinData.currentValue

number

required

Current market value of the coins in USD

Example:

5.851540654

transfers

object[]

List of transfers involved in the transaction (e.g., coins received/sent)

Show child attributes

transfers.transferType

enum<string>

required

Type of transfer operation

Available options:

Received,

Sent

Example:

"Received"

transfers.items

object[]

required

List of items involved in the transfer

Show child attributes

transfers.items.coin

object

required

Information about the coin being transferred

Show child attributes

transfers.items.coin.rank

number

required

Market rank of the coin

Example:

2

transfers.items.coin.identifier

string

required

Unique identifier for the coin

Example:

"ethereum"

transfers.items.coin.symbol

string

required

Trading symbol of the coin

Example:

"ETH"

transfers.items.coin.name

string

required

Full name of the coin

Example:

"Ethereum"

transfers.items.coin.icon

string

required

URL to the coin icon image

Example:

"https://static.coinstats.app/coins/1650455629727.png"

transfers.items.coin.priceChange24h

number

required

Price change percentage in the last 24 hours

Example:

-5.74

transfers.items.coin.priceChange1h

number

required

Price change percentage in the last 1 hour

Example:

0.1

transfers.items.coin.priceChange7d

number

required

Price change percentage in the last 7 days

Example:

1.12

transfers.items.coin.volume

number

required

Trading volume in the last 24 hours (USD)

Example:

61315198931.43572

transfers.items.coin.isFake

boolean

Whether the coin is identified as fake

Example:

false

transfers.items.coin.isFiat

boolean

Whether the coin is a fiat currency

Example:

false

transfers.items.count

number

Amount of coins transferred (can be negative for outgoing transfers)

Example:

-0.00000544

transfers.items.toAddress

string

Destination wallet address

Example:

"0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f"

transfers.items.fromAddress

string

Source wallet address

Example:

"0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e"

transfers.items.totalWorth

number

Total worth of the transferred amount in USD

Example:

0.0000054389555199999995

transfers.items.price

number

Price per unit of the coin in USD at the time of transfer

Example:

0.999808

Get Portfolio Transactions Get Portfolio Defi

⌘I

Market Data

Wallet Data

Exchange Connection

NFTs

News

Portfolio

Market Insights

Add Portfolio Transaction

Authorizations

Headers

Query Parameters

Body

Response