Skip to main content

Address Intelligence & Activity

Build dashboards with Plus aggregates: address metadata, priced balances, and transfer events. Plus lives under /v1/... on the same gateway and uses the same bearer token. It returns UI-ready data so you don't have to stitch multiple protocol reads.

What success looks like:

  • GET /v1/addresses/{address}/metadata returns expected labels/type. SPEC →

  • GET /v1/addresses/{address}/balance/details shows correct display units/decimals and pricing. SPEC →

  • GET /v1/asset/transfer-events returns results for your filters and cursor paging works. SPEC →

Address Dashboard​

Address metadata (labels, type)​

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/addresses/pb1ADDRESS.../metadata"

SPEC →

Balance details (symbols, display units, pricing)​

Code snippet
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/addresses/pb1ADDRESS.../balance/details"

SPEC →

Transfer events (filters + cursor)​

Code snippet
# Example: recent inbound transfers for an address, one denom, since a start time
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/asset/transfer-events?recipient=pb1ADDRESS...&denom=nhash&start_time=2025-01-01T00:00:00Z"

This endpoint is cursor-paged: read next_cursor from the response and pass ?cursor=<next_cursor> to fetch the next page.

Code snippet
# Paging pattern (cursor):
# 1) Call without ?cursor to start; 2) read `next_cursor` from the response;
# 3) call again with ?cursor=<next_cursor> until `next_cursor` is empty/absent.
# Example (pseudo):
NEXT=""
while :; do
  URL="$PROV_PLUS_BASE/v1/asset/transfer-events?recipient=pb1ADDRESS...&start_time=2025-01-01T00:00:00Z"
  [ -n "$NEXT" ] && URL="$URL&cursor=$NEXT"
  RESP=$(curl -s -H "Authorization: Bearer $PROV_API_TOKEN" "$URL")
  echo "$RESP" | jq '.items[]'    # process page
  NEXT=$(echo "$RESP" | jq -r '.next_cursor // empty')
  [ -z "$NEXT" ] && break
done
Code snippet
# Pseudocode for paging
GET /v1/asset/transfer-events?recipient=pb1...&start_time=2025-01-01T00:00:00Z
# ← response: { items:[...], next_cursor:"abc123" }
GET /v1/asset/transfer-events?cursor=abc123
# ← response: { items:[...], next_cursor:"def456" }
# repeat until next_cursor is absent

SPEC →

You can filter results by sender, recipient, denom, event_types, start_time, end_time, or a specific tx_hash; plus cursor and limit for pagination (and direction for sort). See the Transfer Events spec for parameter details.

This endpoint is cursor-paged: read next_cursor from the response and pass ?cursor=<next_cursor> with the same filters to fetch the next page.

Code snippet
# Page 2 (reuse the same filters + cursor)
curl -H "Authorization: Bearer $PROV_API_TOKEN" \
  "$PROV_PLUS_BASE/v1/asset/transfer-events?recipient=pb1ADDRESS...&denom=nhash&start_time=2025-01-01T00:00:00Z&cursor=eyJwYWdlIjoyfQ=="

Time format: use RFC3339 UTC (e.g., 2025-01-01T00:00:00Z). Tip: For consistent pagination, always keep your original filters and only add cursor.

Use-cases (Read)​

Use Cases​

Proof of funds / activity timeline

  • Fetch /v1/addresses/\{address\}/balance/details (priced snapshot) SPEC →
  • Fetch /v1/asset/transfer-events with a time window; page using next_cursor SPEC →

Wallet overview widget

  • /v1/addresses/\{address\}/metadata for type/labels (show account type/name) SPEC →
  • /v1/addresses/\{address\}/balance/details for display units/prices (per-denom totals) SPEC →

Ops audit (investigate funding to an account)

  • Start with /v1/asset/transfer-events?recipient=\{addr\}&start_time=...
  • Page forward with ?cursor=... until the window is covered
  • SPEC →

Common Error Handling Example​

Invalid address (Bech32)

code: invalid_argumentmessage: Invalid Bech32 address format.

Fix: Normalize to a valid pb1… address first (use Name Resolve + Bech32 helpers in "Address Inspector").

Invalid/expired cursor

code: invalid_argumentmessage: Invalid cursor

Fix: Restart from the first page (no cursor) and resume with the new next_cursor.

Empty results Not an error; means no events match your filters/time window. Adjust filters or widen the window.

Rate/limits

code: resource_exhausted

Fix: Back off and retry; keep page sizes reasonable and prefer cursors over very large time windows.