Trades

Overview

The Trades API allows you to manage trades for investment and cryptocurrency accounts. Trades represent buy/sell transactions of securities like stocks, ETFs, crypto, and other financial instruments.

List
Get
Create
Update
Delete

List trades

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

Retrieve a paginated list of trades with optional filtering.

Query parameters

page

integer

default:"1"

Page number for pagination

per_page

integer

default:"25"

Number of trades per page (max 100)

account_id

integer

Filter by single account ID

account_ids

array

Filter by multiple account IDs

start_date

string

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

end_date

string

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

Response

trades

array

Array of trade objects

Show Trade object

integer

Unique identifier for the trade

date

string

Trade date (YYYY-MM-DD)

amount

string

Total trade value formatted as currency string

currency

string

Three-letter ISO currency code

name

string

Trade description (e.g., “Buy 10 shares of AAPL”)

notes

string

Additional notes

qty

number

Quantity of shares (positive for buy, negative for sell)

price

string

Price per share formatted as currency string

investment_activity_label

string

Activity label: Buy, Sell, Sweep In, Sweep Out, Dividend, Reinvestment, Interest, Fee, Transfer, Contribution, Withdrawal, Exchange, or Other

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

Get a trade

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

Retrieve a specific trade by ID.

Path parameters

integer

required

Trade ID

Response

Returns a trade object.

{
  "id": 501,
  "date": "2024-01-10",
  "amount": "$1,750.00",
  "currency": "USD",
  "name": "Buy 10 shares of AAPL",
  "notes": null,
  "qty": 10,
  "price": "$175.00",
  "investment_activity_label": "Buy",
  "account": {
    "id": 3,
    "name": "Vanguard 401(k)",
    "account_type": "investment"
  },
  "security": {
    "id": 100,
    "ticker": "AAPL",
    "name": "Apple Inc."
  },
  "category": null,
  "created_at": "2024-01-10T09:30:00Z",
  "updated_at": "2024-01-10T09:30:00Z"
}

Create a trade

curl -X POST https://api.sure.app/v1/trades \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trade": {
      "account_id": 3,
      "date": "2024-01-10",
      "type": "buy",
      "ticker": "AAPL",
      "qty": 10,
      "price": 175.00,
      "currency": "USD"
    }
  }'

Create a new trade.

Request body

trade

object

required

Show Trade parameters

account_id

integer

required

ID of the investment or crypto account for this trade

date

string

required

Trade date in YYYY-MM-DD format

type

string

required

Trade type: buy or sell

qty

number

required

Quantity of shares (must be positive)

price

number

required

Price per share (must be positive)

security_id

integer

ID of an existing security (use this OR ticker/manual_ticker)

ticker

string

Ticker symbol, optionally with exchange (e.g., “AAPL” or “AAPL|XNAS”)

manual_ticker

string

Manual ticker for securities not in the database

currency

string

Three-letter ISO currency code (defaults to account currency)

investment_activity_label

string

Activity label: Buy, Sell, Sweep In, Sweep Out, Dividend, Reinvestment, Interest, Fee, Transfer, Contribution, Withdrawal, Exchange, or Other

category_id

integer

Category ID

Response

Returns the created trade object.

{
  "id": 503,
  "date": "2024-01-10",
  "amount": "$1,750.00",
  "currency": "USD",
  "name": "Buy 10 shares of AAPL",
  "notes": null,
  "qty": 10,
  "price": "$175.00",
  "investment_activity_label": "Buy",
  "account": {
    "id": 3,
    "name": "Vanguard 401(k)",
    "account_type": "investment"
  },
  "security": {
    "id": 100,
    "ticker": "AAPL",
    "name": "Apple Inc."
  },
  "category": null,
  "created_at": "2024-01-10T16:45:00Z",
  "updated_at": "2024-01-10T16:45:00Z"
}

Update a trade

curl -X PUT https://api.sure.app/v1/trades/501 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trade": {
      "qty": 12,
      "price": 180.00,
      "notes": "Adjusted quantity"
    }
  }'

Update an existing trade.

Path parameters

integer

required

Trade ID

Request body

trade

object

required

Show Trade parameters

name

string

Trade description

date

string

Trade date in YYYY-MM-DD format

qty

number

Quantity of shares

price

number

Price per share

type

string

Trade type: buy or sell (updates qty sign)

nature

string

Alternative to type: inflow (sell) or outflow (buy)

amount

number

Total trade value (calculated from qty * price if not provided)

currency

string

Three-letter ISO currency code

notes

string

Additional notes

investment_activity_label

string

Activity label

category_id

integer

Category ID

Response

Returns the updated trade object.

{
  "id": 501,
  "date": "2024-01-10",
  "amount": "$2,160.00",
  "currency": "USD",
  "name": "Buy 12 shares of AAPL",
  "notes": "Adjusted quantity",
  "qty": 12,
  "price": "$180.00",
  "investment_activity_label": "Buy",
  "account": {
    "id": 3,
    "name": "Vanguard 401(k)",
    "account_type": "investment"
  },
  "security": {
    "id": 100,
    "ticker": "AAPL",
    "name": "Apple Inc."
  },
  "category": null,
  "created_at": "2024-01-10T09:30:00Z",
  "updated_at": "2024-01-10T17:00:00Z"
}

Delete a trade

curl -X DELETE https://api.sure.app/v1/trades/501 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Delete a trade permanently.

Path parameters

integer

required

Trade ID

Response

{
  "message": "Trade deleted successfully"
}

Investment activity labels

Trades can be tagged with activity labels for better categorization:

Label	Description
Buy	Purchase of securities
Sell	Sale of securities
Sweep In	Automatic cash sweep into account
Sweep Out	Automatic cash sweep out of account
Dividend	Dividend payment
Reinvestment	Dividend reinvestment
Interest	Interest earned
Fee	Account or trade fee
Transfer	Transfer between accounts
Contribution	Account contribution
Withdrawal	Account withdrawal
Exchange	Currency or security exchange
Other	Other activity

Account requirements

Trades can only be created for accounts that support them:

Investment accounts: Always support trades
Crypto accounts: Only support trades if subtype is “exchange”
Other account types: Do not support trades

Getting Started

Resources

Overview

List trades

Query parameters

Response

Get a trade

Path parameters

Response

Create a trade

Request body

Response

Update a trade

Path parameters

Request body

Response

Delete a trade

Path parameters

Response

Investment activity labels

Account requirements

Build docs developers (and LLMs) love

Getting Started

Resources

​Overview

​List trades

​Query parameters

​Response

​Get a trade

​Path parameters

​Response

​Create a trade

​Request body

​Response

​Update a trade

​Path parameters

​Request body

​Response

​Delete a trade

​Path parameters

​Response

​Investment activity labels

​Account requirements

Build docs developers (and LLMs) love

Overview

List trades

Query parameters

Response

Get a trade

Path parameters

Response

Create a trade

Request body

Response

Update a trade

Path parameters

Request body

Response

Delete a trade

Path parameters

Response

Investment activity labels

Account requirements