Holdings

Overview

The Holdings API provides read-only access to security holdings in investment and cryptocurrency accounts. Holdings represent point-in-time snapshots of positions, including quantity, market value, and cost basis information.

List
Get

List holdings

curl -X GET "https://api.sure.app/v1/holdings?account_id=3&date=2024-01-31" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Retrieve a paginated list of holdings with optional filtering.

Query parameters

page

integer

default:"1"

Page number for pagination

per_page

integer

default:"25"

Number of holdings per page (max 100)

account_id

integer

Filter by single account ID

account_ids

array

Filter by multiple account IDs

security_id

integer

Filter by security ID

date

string

Filter holdings for a specific date (YYYY-MM-DD)

start_date

string

Filter holdings on or after this date (YYYY-MM-DD)

end_date

string

Filter holdings on or before this date (YYYY-MM-DD)

Response

holdings

array

Array of holding objects

Show Holding object

integer

Unique identifier for the holding

date

string

Date of the holding snapshot (YYYY-MM-DD)

qty

number

Quantity of shares held

price

string

Current price per share formatted as currency string

amount

string

Total market value formatted as currency string

currency

string

Three-letter ISO currency code

cost_basis_source

string

Source of cost basis data: manual, calculated, or provider

avg_cost

string

Average cost per share formatted as currency string (null if unknown)

account

object

Account information

Show Account

integer

Account ID

name

string

Account name

account_type

string

Account type

security

object

Security information

Show Security

integer

Security ID

ticker

string

Ticker symbol

name

string

Security name

created_at

string

ISO 8601 timestamp

updated_at

string

ISO 8601 timestamp

pagination

object

Pagination metadata

{
  "holdings": [
    {
      "id": 1001,
      "date": "2024-01-31",
      "qty": 10,
      "price": "$185.50",
      "amount": "$1,855.00",
      "currency": "USD",
      "cost_basis_source": "calculated",
      "avg_cost": "$175.00",
      "account": {
        "id": 3,
        "name": "Vanguard 401(k)",
        "account_type": "investment"
      },
      "security": {
        "id": 100,
        "ticker": "AAPL",
        "name": "Apple Inc."
      },
      "created_at": "2024-01-31T23:59:00Z",
      "updated_at": "2024-01-31T23:59:00Z"
    },
    {
      "id": 1002,
      "date": "2024-01-31",
      "qty": 50,
      "price": "$450.75",
      "amount": "$22,537.50",
      "currency": "USD",
      "cost_basis_source": "provider",
      "avg_cost": "$425.00",
      "account": {
        "id": 3,
        "name": "Vanguard 401(k)",
        "account_type": "investment"
      },
      "security": {
        "id": 101,
        "ticker": "GOOGL",
        "name": "Alphabet Inc."
      },
      "created_at": "2024-01-31T23:59:00Z",
      "updated_at": "2024-01-31T23:59:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 2,
    "total_pages": 1
  }
}

Get a holding

curl -X GET https://api.sure.app/v1/holdings/1001 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Retrieve a specific holding by ID.

Path parameters

integer

required

Holding ID

Response

Returns a holding object.

{
  "id": 1001,
  "date": "2024-01-31",
  "qty": 10,
  "price": "$185.50",
  "amount": "$1,855.00",
  "currency": "USD",
  "cost_basis_source": "calculated",
  "avg_cost": "$175.00",
  "account": {
    "id": 3,
    "name": "Vanguard 401(k)",
    "account_type": "investment"
  },
  "security": {
    "id": 100,
    "ticker": "AAPL",
    "name": "Apple Inc."
  },
  "created_at": "2024-01-31T23:59:00Z",
  "updated_at": "2024-01-31T23:59:00Z"
}

Cost basis sources

Holdings may have cost basis information from different sources:

Source	Description	Priority
`manual`	User-entered cost basis	Highest
`calculated`	Calculated from trade history	Medium
`provider`	Provided by financial institution	Lowest

The cost_basis_source field indicates where the average cost data originated. Higher priority sources take precedence when multiple sources are available.

Understanding holdings

Snapshots over time

Holdings represent point-in-time snapshots of security positions. Each holding record shows:

Date: The date of the snapshot
Quantity: Number of shares held on that date
Price: Market price per share on that date
Amount: Total market value (qty × price)
Average cost: Cost basis per share (if known)

Gain/loss calculation

To calculate unrealized gain/loss for a holding:

Market Value = qty × price
Cost Basis = qty × avg_cost
Unrealized Gain/Loss = Market Value - Cost Basis

Note that avg_cost may be null if cost basis information is not available.

Read-only resource

Holdings are automatically calculated from trades and account syncs. They cannot be created, updated, or deleted directly through the API. To modify holdings:

Create or update trades for the security
Sync the account with your financial institution
The system will automatically recalculate holdings

Error responses

error

string

Error code identifier

message

string

Human-readable error description

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Getting Started

Resources

Overview

List holdings

Query parameters

Response

Get a holding

Path parameters

Response

Cost basis sources

Understanding holdings

Snapshots over time

Gain/loss calculation

Read-only resource

Error responses

Build docs developers (and LLMs) love

Getting Started

Resources

​Overview

​List holdings

​Query parameters

​Response

​Get a holding

​Path parameters

​Response

​Cost basis sources

​Understanding holdings

​Snapshots over time

​Gain/loss calculation

​Read-only resource

​Error responses

Build docs developers (and LLMs) love

Overview

List holdings

Query parameters

Response

Get a holding

Path parameters

Response

Cost basis sources

Understanding holdings

Snapshots over time

Gain/loss calculation

Read-only resource

Error responses