Skip to main content
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,
      "priceChange1m": 8.42,
      "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,
            "priceChange1m": 8.42,
            "volume": 61315198931.43572,
            "isFake": false,
            "isFiat": false
          },
          "count": -0.00000544,
          "toAddress": "0x42382d7853beb8d0ec968de4184a6a3c89cf6b5f",
          "fromAddress": "0x8ac77cbf06b44ec918e4ed99698e83a0be222e0e",
          "totalWorth": 0.0000054389555199999995,
          "price": 0.999808
        }
      ]
    }
  ],
  "note": {
    "name": "KuCoin Spot",
    "icon": "https://static.coinstats.app/portfolio_images/kucoin_dark.png"
  }
}
4 credits per request
  • Support for buy, sell, and transfer operations
  • Automatically updates your portfolio holdings
  • Validates transaction data before recording
  • Returns the details of the created transaction
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)
  • 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 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.

Headers

​
sharetoken
string

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

​
fee
object
required

Transaction fee information

​
portfolioInfo
object
required

Information about the portfolio where the transaction occurred

​
coinData
object

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

​
transfers
object[]

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

​
note
object

Transaction Notes