Portfolio

Overview

The Portfolio API gives you the account-level view after users deposit, withdraw, trade, transfer funds, or earn rewards. Use it to show current portfolio value, per-asset balances, an activity feed, and historical performance. Subscribe to Portfolio transaction webhooks when you want change notifications without continuous polling. All Portfolio endpoints are scoped to a specific account_id. Pass the same quote_symbol across related calls when you want summary values, holdings, history, and transaction amounts to line up in the same currency.

Prerequisites

Payward Services API credentials (see the Authentication guide)
A verified user with at least one account
Base URL: https://api.services.payward.com

Portfolio workflow

Use this flow when you build a portfolio dashboard or reconcile user activity after payments and trades.

Show the account summary

Fetch total value, available value, withheld value, open-order value, and unrealized PnL.GET /v1/accounts/{account_id}/portfolio/summary

List asset positions

Fetch the asset-level balance breakdown for the portfolio.GET /v1/accounts/{account_id}/portfolio/details

Build the activity feed

Fetch transaction history for deposits, withdrawals, transfers, swaps, price trigger swaps, and earn rewards.GET /v1/accounts/{account_id}/portfolio/transactions

Subscribe to transaction changes

Register for transaction.* webhook events. Retrieve the complete transaction from Portfolio after each notification.POST /v1/webhooks

Chart portfolio performance

Fetch historical balances and valuations for a selected time window.GET /v1/accounts/{account_id}/portfolio/history

Step 1: show the account summary

Call GET /v1/accounts/{account_id}/portfolio/summary to get the top-level values for a portfolio dashboard.

def get_portfolio_summary(account_id, quote_symbol="USD", quote_type="fiat"):
    endpoint = f"/v1/accounts/{account_id}/portfolio/summary"
    params = {"quote_symbol": quote_symbol, "quote_type": quote_type}
    signature = get_payward_signature(endpoint, None, API_SECRET, params)

    headers = {
        "API-Key": API_KEY,
        "API-Sign": signature,
    }

    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        params=params,
    )
    return response.json()


summary = get_portfolio_summary("ABCD1234EFGH5678")
print(summary["data"]["value"])

async function getPortfolioSummary(accountId, quoteSymbol = 'USD', quoteType = 'fiat') {
  const endpoint = `/v1/accounts/${accountId}/portfolio/summary`;
  const params = new URLSearchParams({ quote_symbol: quoteSymbol, quote_type: quoteType });
  const signature = getPaywardSignature(endpoint, null, API_SECRET, params);

  const response = await fetch(`${BASE_URL}${endpoint}?${params}`, {
    method: 'GET',
    headers: {
      'API-Key': API_KEY,
      'API-Sign': signature,
    },
  });

  return response.json();
}

const summary = await getPortfolioSummary('ABCD1234EFGH5678');
console.log(summary.data.value);

Use these fields for the dashboard header:

Field	How to use it
`value`	Total portfolio value in the requested `quote_symbol`.
`cost_basis`	Total cost basis of the portfolio, when available.
`available`	Value freely available for trading or withdrawal.
`withheld`	Value reserved across pending withdrawals, earn bonding or unbonding, and other platform holds.
`open_orders`	Value held for open orders.
`pnl.unrealized`	Unrealized profit and loss, when available.

See the Get Portfolio Summary API reference for the full response schema.

Step 2: list asset positions

Call GET /v1/accounts/{account_id}/portfolio/details to show the user’s holdings by asset.

def list_portfolio_details(account_id, quote_symbol="USD", quote_type="fiat"):
    endpoint = f"/v1/accounts/{account_id}/portfolio/details"
    params = {"quote_symbol": quote_symbol, "quote_type": quote_type}

    signature = get_payward_signature(endpoint, None, API_SECRET, params)
    headers = {
        "API-Key": API_KEY,
        "API-Sign": signature,
    }

    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        params=params,
    )
    return response.json()


positions = list_portfolio_details("ABCD1234EFGH5678")
for position in positions["data"]:
    print(position["symbol"], position["total"], position["total_in_quote"])

async function listPortfolioDetails(accountId, quoteSymbol = 'USD', quoteType = 'fiat') {
  const endpoint = `/v1/accounts/${accountId}/portfolio/details`;
  const params = new URLSearchParams({ quote_symbol: quoteSymbol, quote_type: quoteType });

  const signature = getPaywardSignature(endpoint, null, API_SECRET, params);
  const response = await fetch(`${BASE_URL}${endpoint}?${params}`, {
    method: 'GET',
    headers: {
      'API-Key': API_KEY,
      'API-Sign': signature,
    },
  });

  return response.json();
}

const positions = await listPortfolioDetails('ABCD1234EFGH5678');
for (const position of positions.data) {
  console.log(position.symbol, position.total, position.total_in_quote);
}

Use these fields for each position:

Field	How to use it
`symbol`	Identify the held asset.
`total`	Total balance in the asset itself.
`total_in_quote`	Total position value in the requested `quote_symbol`.
`available`	Balance available after holds.
`available_in_quote`	Available balance value in the requested `quote_symbol`.
`open_orders`	Asset amount held in open orders.
`index_price`	Price used for current valuation in the response quote asset.
`avg_entry_price_in_quote`	Average acquisition price in the response quote asset, when known.
`cost_basis_in_quote`	Cost basis in the response quote asset, when known.
`pnl.unrealized`	Unrealized PnL for the currently held lots.
`pnl.realized`	Total realized PnL for the asset.
`pnl.reference_currency.symbol`	Currency symbol to use when displaying PnL amounts.
`pnl.reference_currency.type`	Asset type for the PnL reference currency.
`pnl.status.unrealized`	Processing status for the unrealized PnL value.
`pnl.status.realized`	Processing status for the realized PnL value.

The pnl object is optional. pnl.status can appear without PnL amounts. pnl.unrealized and pnl.realized are returned only when the amount is available and PWS can expose its reference currency. When either amount is returned, pnl.reference_currency is returned with it. If a status field is in_progress, the corresponding PnL value is still being calculated and might be absent or not final. Use pnl.reference_currency when displaying PnL amounts instead of assuming that PnL always uses the requested quote_symbol. See the List Portfolio Details API reference for all query parameters and response fields.

Step 3: build the activity feed

Call GET /v1/accounts/{account_id}/portfolio/transactions to list user-visible portfolio activity. Use it after a deposit, withdrawal, swap, price trigger swap, or earn reward to show what changed and support reconciliation.

def list_portfolio_transactions(account_id, page_token=None):
    endpoint = f"/v1/accounts/{account_id}/portfolio/transactions"
    params = [
        ("types", "deposit"),
        ("types", "withdrawal"),
        ("types", "swap"),
        ("statuses", "successful"),
        ("start_timestamp", "2026-04-01T00:00:00Z"),
        ("end_timestamp", "2026-04-30T23:59:59Z"),
        ("sort_direction", "desc"),
        ("quote_symbol", "USD"),
        ("quote_type", "fiat"),
        ("page_size", "20"),
    ]
    if page_token:
        params.append(("page_token", page_token))

    signature = get_payward_signature(endpoint, None, API_SECRET, params)
    headers = {
        "API-Key": API_KEY,
        "API-Sign": signature,
    }

    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        params=params,
    )
    return response.json()


transactions = list_portfolio_transactions("ABCD1234EFGH5678")
for transaction in transactions["data"]:
    print(transaction["timestamp"], transaction["type"], transaction.get("status"))

async function listPortfolioTransactions(accountId, pageToken = null) {
  const endpoint = `/v1/accounts/${accountId}/portfolio/transactions`;
  const params = new URLSearchParams();
  params.append('types', 'deposit');
  params.append('types', 'withdrawal');
  params.append('types', 'swap');
  params.append('statuses', 'successful');
  params.set('start_timestamp', '2026-04-01T00:00:00Z');
  params.set('end_timestamp', '2026-04-30T23:59:59Z');
  params.set('sort_direction', 'desc');
  params.set('quote_symbol', 'USD');
  params.set('quote_type', 'fiat');
  params.set('page_size', '20');
  if (pageToken) params.set('page_token', pageToken);

  const signature = getPaywardSignature(endpoint, null, API_SECRET, params);
  const response = await fetch(`${BASE_URL}${endpoint}?${params}`, {
    method: 'GET',
    headers: {
      'API-Key': API_KEY,
      'API-Sign': signature,
    },
  });

  return response.json();
}

const transactions = await listPortfolioTransactions('ABCD1234EFGH5678');
for (const transaction of transactions.data) {
  console.log(transaction.timestamp, transaction.type, transaction.status);
}

Common filters:

Filter	How to use it
`types`	Filter by `swap`, `price_trigger_swap`, `earn_reward`, `deposit`, `withdrawal`, or `transfer`.
`statuses`	Filter by `in_progress`, `successful`, `failed`, `no_status`, or `uncategorized`.
`start_timestamp` and `end_timestamp`	Restrict results to a time window.
`assets`	Filter by asset references using indexed deep-object syntax.
`ids`	Look up specific portfolio transaction IDs.
`sort_direction`	Return newest-first with `desc` or oldest-first with `asc`.
`quote_symbol`	Add best-effort `amount_in_quote` values to spend, receive, and fee amounts. Defaults to `USD`.
`quote_type`	Use `fiat`. Other quote types are not currently supported.

Each transaction can include spend, receive, or both. Failed transactions can omit movement details, so build your UI around the required fields id, timestamp, and type, then display optional money movement fields when present. Deposits and withdrawals can also carry details with type: "funding" and a crypto_transaction_id you can use to link to a block explorer. It appears once the transaction settles on a blockchain, and is omitted for fiat funding. swap and price_trigger_swap represent executed transactions. Failed execution attempts do not appear in this endpoint. Use next_page_token as page_token to fetch more transactions. See the List Portfolio Transactions API reference for all filters and response fields. Register a webhook to receive change notifications for the Portfolio transaction categories you use. One webhook can subscribe to any combination of these events:

Event type	Portfolio transaction category	Correlation fields when available
`transaction.swap`	`swap`	`quote_id`
`transaction.price_trigger_swap`	`price_trigger_swap`	`quote_id`
`transaction.earn_reward`	`earn_reward`	`strategy_id`, `reward_id`
`transaction.deposit`	`deposit`	`funding_reference`, `crypto_transaction_id`
`transaction.withdrawal`	`withdrawal`	`funding_reference`, `crypto_transaction_id`
`transaction.transfer`	`transfer`	`transfer_id`

Every payload contains type, transaction_id, user_id, account_id, and timestamp. It can also contain status. Treat the webhook as a change notification. Use transaction_id as the ids filter on GET /v1/accounts/{account_id}/portfolio/transactions to retrieve the complete ledger entry. The same transaction can emit more than one event as its status changes. Deduplicate delivery retries with the svix-id header.

Failed swap and price trigger swap execution attempts do not emit transaction.* events because they do not contain ledger movements. Use the relevant quote or price trigger swap failure event instead.

See the Register Webhook API reference to create a subscription and review the event payload schemas.

Step 5: chart portfolio performance

Call GET /v1/accounts/{account_id}/portfolio/history to draw a portfolio value chart or show how balances changed over time.

def list_portfolio_history(account_id):
    endpoint = f"/v1/accounts/{account_id}/portfolio/history"
    params = [
        ("start_timestamp", "2026-04-01T00:00:00Z"),
        ("end_timestamp", "2026-04-30T23:59:59Z"),
        ("quote_symbol", "USD"),
        ("quote_type", "fiat"),
        ("assets[0][symbol]", "BTC"),
        ("assets[0][type]", "crypto"),
        ("assets[1][symbol]", "ETH"),
        ("assets[1][type]", "crypto"),
    ]

    signature = get_payward_signature(endpoint, None, API_SECRET, params)
    headers = {
        "API-Key": API_KEY,
        "API-Sign": signature,
    }

    response = requests.get(
        f"{BASE_URL}{endpoint}",
        headers=headers,
        params=params,
    )
    return response.json()


history = list_portfolio_history("ABCD1234EFGH5678")
for point in history["data"]:
    print(point["timestamp"], point.get("value"))

async function listPortfolioHistory(accountId) {
  const endpoint = `/v1/accounts/${accountId}/portfolio/history`;
  const params = new URLSearchParams();
  params.set('start_timestamp', '2026-04-01T00:00:00Z');
  params.set('end_timestamp', '2026-04-30T23:59:59Z');
  params.set('quote_symbol', 'USD');
  params.set('quote_type', 'fiat');
  params.set('assets[0][symbol]', 'BTC');
  params.set('assets[0][type]', 'crypto');
  params.set('assets[1][symbol]', 'ETH');
  params.set('assets[1][type]', 'crypto');

  const signature = getPaywardSignature(endpoint, null, API_SECRET, params);
  const response = await fetch(`${BASE_URL}${endpoint}?${params}`, {
    method: 'GET',
    headers: {
      'API-Key': API_KEY,
      'API-Sign': signature,
    },
  });

  return response.json();
}

const history = await listPortfolioHistory('ABCD1234EFGH5678');
for (const point of history.data) {
  console.log(point.timestamp, point.value);
}

Use the history endpoint for:

Portfolio value charts with timestamp and value.
Historical PnL views with total_pnl, when available.
Historical asset-balance charts when you request assets filters with both symbol and type.
Quote-aware charts with top-level quote_symbol, quote_type, start_timestamp, and end_timestamp.

The history endpoint returns a maximum of 365 data points per request. Use a narrower time window when you need fewer points.

A missing asset balance at the start of the range means the user did not hold that asset at that time. A zero balance means the user may have held the asset previously, but did not hold it at that snapshot. The latest daily balance can be delayed by up to about five hours after UTC midnight while data is processed.

See the List Portfolio History API reference for all query parameters and response fields.

API reference

Endpoint	Method	Description
`/v1/accounts/{account_id}/portfolio/summary`	GET	Get total portfolio value, availability, holds, and unrealized PnL
`/v1/accounts/{account_id}/portfolio/details`	GET	List asset-level balances, valuation, open orders, cost basis, and PnL
`/v1/accounts/{account_id}/portfolio/transactions`	GET	List portfolio transactions for deposits, withdrawals, transfers, swaps, and earn rewards
`/v1/accounts/{account_id}/portfolio/history`	GET	List historical balances and valuations for a portfolio
`/v1/webhooks`	POST	Subscribe to Portfolio transaction change notifications

Get started

Market data

Accounts

Verifications

Trade

Earn

Payments

Overview

Prerequisites

Portfolio workflow

Step 1: show the account summary

Step 2: list asset positions

Step 3: build the activity feed

Step 5: chart portfolio performance

API reference

​Overview

​Prerequisites

​Portfolio workflow

​Step 1: show the account summary

​Step 2: list asset positions

​Step 3: build the activity feed

​Step 4: subscribe to transaction changes

​Step 5: chart portfolio performance

​API reference

Overview

Prerequisites

Portfolio workflow

Step 1: show the account summary

Step 2: list asset positions

Step 3: build the activity feed

Step 4: subscribe to transaction changes

Step 5: chart portfolio performance

API reference