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 and quote_type across the current portfolio, history, and transaction calls when you want their monetary values to use the same quote asset.

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 current portfolio

Fetch account-level values and the per-asset balance breakdown in one snapshot.GET /v1/accounts/{account_id}/portfolio

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: get the current portfolio

Call GET /v1/accounts/{account_id}/portfolio to get the account totals and per-asset balances in one consistent snapshot. Set with_zero_balances=true when you also need assets with zero balances, such as when you display every supported asset.

def get_portfolio(
    account_id, quote_symbol="USD", quote_type="fiat", with_zero_balances=False
):
    endpoint = f"/v1/accounts/{account_id}/portfolio"
    params = {
        "quote_symbol": quote_symbol,
        "quote_type": quote_type,
        "with_zero_balances": str(with_zero_balances).lower(),
    }
    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()


portfolio = get_portfolio("ABCD1234EFGH5678")
print(portfolio["data"]["total_in_quote"])
for asset in portfolio["data"]["assets"]:
    print(
        asset["symbol"],
        asset["balances"]["total"],
        asset["balances"].get("total_in_quote"),
    )

async function getPortfolio(accountId, quoteSymbol = 'USD', quoteType = 'fiat', withZeroBalances = false) {
  const endpoint = `/v1/accounts/${accountId}/portfolio`;
  const params = new URLSearchParams({
    quote_symbol: quoteSymbol,
    quote_type: quoteType,
    with_zero_balances: String(withZeroBalances),
  });
  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 portfolio = await getPortfolio('ABCD1234EFGH5678');
console.log(portfolio.data.total_in_quote);
for (const asset of portfolio.data.assets) {
  console.log(asset.symbol, asset.balances.total, asset.balances.total_in_quote);
}

Use these account-level fields for the dashboard header:

Field	How to use it
`as_of`	Show when the latest index price in the snapshot was updated.
`quote`	Identify the quote asset used by monetary values throughout the snapshot.
`total_in_quote`	Show total account value in the quote asset.
`availability.available_in_quote`	Show funds available for trading or withdrawal after holds.
`availability.withheld.*_in_quote`	Explain amounts held for open orders, earn products, or other temporary holds.
`pnl.*_in_quote`	Show account-level average-cost-basis PnL when available.
`assets`	Render the per-asset balance breakdown from the same snapshot.

For each item in assets, use these fields:

Field	How to use it
`symbol` and `type`	Identify the asset unambiguously.
`index_price_in_quote`	Show the price of one native asset unit in the top-level quote asset.
`balances.total`	Show the balance in the asset’s native display units.
`balances.total_in_quote`	Show the value of that same total in the top-level quote asset.
`balances.main`	Show balances held in the main source, including balances used by spot trading and received from swaps.
`held_for_orders`	Show native asset amounts held for open orders.
`earn`	Break earn balances down by liquidity state and yield source.
`availability`	Show native amounts available for trading or internal transfer.
`credit_line`, `spot_margin`, and `pnl`	Add credit and explicitly quoted spot-margin and average-cost-basis details when they apply.

Quote-denominated monetary amounts end in _in_quote. Native asset amounts omit that suffix. For example, balances.total is an amount in the asset itself; it is not a price. Use balances.total_in_quote when you need its value in data.quote. The nested balance sources use the same total and total_in_quote naming. Account-level availability is an aggregate in data.quote; it does not belong inside balances.main. Per-asset availability.trade and availability.transfer are native amounts for those actions. The pnl objects are optional. A PnL status can be in_progress while its corresponding value is absent or not final. Numeric PnL fields ending in _in_quote use data.quote. pnl.reference_currency identifies Portfolio’s calculation basis; it does not change the display currency. See the Get portfolio API reference for every query parameter and response field.

Step 2: 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["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`, or `failed`.
`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 returned transaction includes the required fields id, timestamp, type, and status. It can include spend, receive, or both. Failed transactions can omit movement details. Transactions without a defined lifecycle status are not returned. 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. Successful swap and price_trigger_swap transactions include details.quote_id. Use it to correlate the transaction with the quote that executed it. Failed swap attempts appear with status: "failed". Their details use type: "failed_swap" or type: "failed_price_trigger_swap" and include failure_reason. The reason is one of insufficient_funds, card_issue, user_account_issue, or other. 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 4: 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`	GET	Get account-level values and per-asset balances in one snapshot
`/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: get the current portfolio

Step 2: build the activity feed

Step 4: chart portfolio performance

API reference

​Overview

​Prerequisites

​Portfolio workflow

​Step 1: get the current portfolio

​Step 2: build the activity feed

​Step 3: subscribe to transaction changes

​Step 4: chart portfolio performance

​API reference

Overview

Prerequisites

Portfolio workflow

Step 1: get the current portfolio

Step 2: build the activity feed

Step 3: subscribe to transaction changes

Step 4: chart portfolio performance

API reference