Add a new transaction to your manual portfolio
curl --request POST \
--url https://api.coinstats.app/v1/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."
}
'import requests
url = "https://api.coinstats.app/v1/portfolio/transaction"
payload = {
"coinId": "bitcoin",
"count": 0.1,
"date": 1715948176654,
"price": 66252.93,
"portfolioId": "xobgM6CHi1zaEJaCXmPWenVoS",
"currency": "USD",
"notes": "Some notes."
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
coinId: 'bitcoin',
count: 0.1,
date: 1715948176654,
price: 66252.93,
portfolioId: 'xobgM6CHi1zaEJaCXmPWenVoS',
currency: 'USD',
notes: 'Some notes.'
})
};
fetch('https://api.coinstats.app/v1/portfolio/transaction', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coinstats.app/v1/portfolio/transaction",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'coinId' => 'bitcoin',
'count' => 0.1,
'date' => 1715948176654,
'price' => 66252.93,
'portfolioId' => 'xobgM6CHi1zaEJaCXmPWenVoS',
'currency' => 'USD',
'notes' => 'Some notes.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coinstats.app/v1/portfolio/transaction"
payload := strings.NewReader("{\n \"coinId\": \"bitcoin\",\n \"count\": 0.1,\n \"date\": 1715948176654,\n \"price\": 66252.93,\n \"portfolioId\": \"xobgM6CHi1zaEJaCXmPWenVoS\",\n \"currency\": \"USD\",\n \"notes\": \"Some notes.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coinstats.app/v1/portfolio/transaction")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"coinId\": \"bitcoin\",\n \"count\": 0.1,\n \"date\": 1715948176654,\n \"price\": 66252.93,\n \"portfolioId\": \"xobgM6CHi1zaEJaCXmPWenVoS\",\n \"currency\": \"USD\",\n \"notes\": \"Some notes.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coinstats.app/v1/portfolio/transaction")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"coinId\": \"bitcoin\",\n \"count\": 0.1,\n \"date\": 1715948176654,\n \"price\": 66252.93,\n \"portfolioId\": \"xobgM6CHi1zaEJaCXmPWenVoS\",\n \"currency\": \"USD\",\n \"notes\": \"Some notes.\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}{
"statusCode": 400,
"message": "Bad Request",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 401,
"message": "Unauthorized",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 403,
"message": "Forbidden",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 404,
"message": "Not Found",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 409,
"message": "Transactions not synced",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 429,
"message": "Rate limit exceeded",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 503,
"message": "Service Unavailable. Please Contact Support"
}User Portfolio
Add Portfolio Transaction
Add a new transaction to your manual portfolio
POST
/
v1
/
portfolio
/
transaction
Add a new transaction to your manual portfolio
curl --request POST \
--url https://api.coinstats.app/v1/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."
}
'import requests
url = "https://api.coinstats.app/v1/portfolio/transaction"
payload = {
"coinId": "bitcoin",
"count": 0.1,
"date": 1715948176654,
"price": 66252.93,
"portfolioId": "xobgM6CHi1zaEJaCXmPWenVoS",
"currency": "USD",
"notes": "Some notes."
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
coinId: 'bitcoin',
count: 0.1,
date: 1715948176654,
price: 66252.93,
portfolioId: 'xobgM6CHi1zaEJaCXmPWenVoS',
currency: 'USD',
notes: 'Some notes.'
})
};
fetch('https://api.coinstats.app/v1/portfolio/transaction', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.coinstats.app/v1/portfolio/transaction",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'coinId' => 'bitcoin',
'count' => 0.1,
'date' => 1715948176654,
'price' => 66252.93,
'portfolioId' => 'xobgM6CHi1zaEJaCXmPWenVoS',
'currency' => 'USD',
'notes' => 'Some notes.'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"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;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.coinstats.app/v1/portfolio/transaction"
payload := strings.NewReader("{\n \"coinId\": \"bitcoin\",\n \"count\": 0.1,\n \"date\": 1715948176654,\n \"price\": 66252.93,\n \"portfolioId\": \"xobgM6CHi1zaEJaCXmPWenVoS\",\n \"currency\": \"USD\",\n \"notes\": \"Some notes.\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.coinstats.app/v1/portfolio/transaction")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"coinId\": \"bitcoin\",\n \"count\": 0.1,\n \"date\": 1715948176654,\n \"price\": 66252.93,\n \"portfolioId\": \"xobgM6CHi1zaEJaCXmPWenVoS\",\n \"currency\": \"USD\",\n \"notes\": \"Some notes.\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.coinstats.app/v1/portfolio/transaction")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"coinId\": \"bitcoin\",\n \"count\": 0.1,\n \"date\": 1715948176654,\n \"price\": 66252.93,\n \"portfolioId\": \"xobgM6CHi1zaEJaCXmPWenVoS\",\n \"currency\": \"USD\",\n \"notes\": \"Some notes.\"\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}{
"statusCode": 400,
"message": "Bad Request",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 401,
"message": "Unauthorized",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 403,
"message": "Forbidden",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 404,
"message": "Not Found",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 409,
"message": "Transactions not synced",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 429,
"message": "Rate limit exceeded",
"requestId": "11111111-2222-3333-4444-555555555555",
"path": "<requested-endpoint>"
}{
"statusCode": 503,
"message": "Service Unavailable. Please Contact Support"
}4 credits per request
You will get
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
Required
- portfolioId (request body): A manual portfolio from GET /portfolio/list
- 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
Optional
- notes: Add personal notes to the transaction
- currency: Specify currency for price (default: USD)
- shareToken and passcode: Legacy alternative to portfolioId for a shared portfolio
Authorizations
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
Passcode for accessing protected portfolio data
Example:
"123456"
Body
application/json
Coin ID from CoinStats API. For fiats you can send coin ID like this: FiatCoinUSD.
Example:
"bitcoin"
Amount of coin. For sell transactions, this should be negative.
Example:
0.1
Transaction date in milliseconds. If not provided, current date will be used.
Example:
1715948176654
Price of coin in USD at the time of transaction.
Example:
66252.93
Target manual portfolio id from GET /portfolio/list. Required unless a shareToken for a single portfolio is used.
Example:
"xobgM6CHi1zaEJaCXmPWenVoS"
Default is USD.
Example:
"USD"
Transaction notes.
Example:
"Some notes."
Response
PortfolioTransactions
Display type of the transaction (e.g., Sent, Received, Swap, Roll In). The full list of supported types is available via GET /portfolio/transactions/types — this field matches its name values.
Example:
"Roll In"
ISO 8601 timestamp of when the transaction occurred
Example:
"2025-08-28T08:35:50.384Z"
Profit and loss information for the transaction
Show child attributes
Show child attributes
Transaction fee information
Show child attributes
Show child attributes
Information about the portfolio where the transaction occurred
Show child attributes
Show child attributes
Main coin data for the transaction (optional for some transaction types)
Show child attributes
Show child attributes
List of transfers involved in the transaction (e.g., coins received/sent)
Show child attributes
Show child attributes
Transaction Notes
Show child attributes
Show child attributes
Was this page helpful?