Portfolio - Payward Developer Documentation

Overview

The Portfolio API gives you the account-level view after users deposit, withdraw, trade, or earn rewards. Use it to show current portfolio value, per-asset balances, an activity feed, and historical performance. 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, trades, price trigger swaps, and earn rewards.GET /v1/accounts/{account_id}/portfolio/transactions

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"])

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"])

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 spot orders.
`index_price`	Price used for current valuation.
`avg_entry_price_in_quote`	Average entry price - when available.
`cost_basis_in_quote`	Cost basis - when available.

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, 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", "simple_order"),
        ("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"))

Common filters:

Filter	How to use it
`types`	Filter by `simple_order`, `simple_order_failed`, `price_trigger_swap`, `price_trigger_swap_failed`, `earn_reward`, or `deposit`.
`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.
`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. Use next_page_token as page_token to fetch more transactions. See the List Portfolio Transactions API reference for all filters and response fields.

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"))

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, and cost basis
`/v1/accounts/{account_id}/portfolio/transactions`	GET	List portfolio transactions for deposits, swaps, price trigger swaps, and earn rewards
`/v1/accounts/{account_id}/portfolio/history`	GET	List historical balances and valuations for a portfolio

​Overview

​Prerequisites

​Portfolio workflow

​Step 1: show the account summary

​Step 2: list asset positions

​Step 3: build the activity feed

​Step 4: 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: chart portfolio performance

API reference