> ## 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.
# Add Portfolio Transaction
> Add a new transaction to your manual portfolio
**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)
## OpenAPI
````yaml /api-reference/openapi.json post /v1/portfolio/transaction
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/transaction:
post:
tags:
- User Portfolio
summary: Add a new transaction to your manual portfolio
operationId: add-portfolio-transaction
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
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddTransactionDto'
responses:
'200':
description: PortfolioTransactions
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionItemDto'
'400':
description: Bad Request
content:
application/json:
example:
statusCode: 400
message: Bad Request
requestId: 11111111-2222-3333-4444-555555555555
path:
'401':
description: Unauthorized
content:
application/json:
example:
statusCode: 401
message: Unauthorized
requestId: 11111111-2222-3333-4444-555555555555
path:
'403':
description: Forbidden
content:
application/json:
example:
statusCode: 403
message: Forbidden
requestId: 11111111-2222-3333-4444-555555555555
path:
'404':
description: Not Found
content:
application/json:
example:
statusCode: 404
message: Not Found
requestId: 11111111-2222-3333-4444-555555555555
path:
'409':
description: Conflict (for some endpoints)
content:
application/json:
example:
statusCode: 409
message: Transactions not synced
requestId: 11111111-2222-3333-4444-555555555555
path:
'429':
description: Too Many Requests
content:
application/json:
example:
statusCode: 429
message: Rate limit exceeded
requestId: 11111111-2222-3333-4444-555555555555
path:
'503':
description: Service Unavailable
content:
application/json:
example:
statusCode: 503
message: Service Unavailable. Please Contact Support
security:
- X-API-KEY: []
components:
schemas:
AddTransactionDto:
type: object
properties:
coinId:
type: string
example: bitcoin
description: >-
Coin ID from CoinStats API. For fiats you can send coin ID like
this: FiatCoinUSD.
count:
type: number
example: 0.1
description: Amount of coin. For sell transactions, this should be negative.
date:
type: number
example: 1715948176654
description: >-
Transaction date in milliseconds. If not provided, current date will
be used.
price:
type: number
example: 66252.93
description: Price of coin in USD at the time of transaction.
portfolioId:
type: string
example: xobgM6CHi1zaEJaCXmPWenVoS
description: >-
If shared portfolio is not manual portfolio, then this field is
required.
currency:
type: string
example: USD
description: Default is USD.
notes:
type: string
example: Some notes.
description: Transaction notes.
required:
- coinId
- count
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
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.
````