Design Philosophy
Our APIs are use-case driven.
We think of data in terms of how it should look like, for a variety of use cases, instead of passing through the raw complexity of how the data lives onchain.
We design our schemes and indexes around the core question of "What's the most useful data representation of _ to easily build _?"
Activity feeds and transaction explorers
Use GET /{chain}/updates/{party} when you want a paginated history for a party.
This is the main endpoint for wallets, dashboards, audit views, and back office tooling. When a user drills into one specific item, GET /{chain}/update/{updateId} gives you the full classified update for that event. If you only need a lightweight size estimate first, GET /{chain}/updates/{party}/count gives you that.
Balance and portfolio views
Use GET /{chain}/balances/{party} to get the party's CC balance together with a USD value.
If your product needs pricing directly, use GET /{chain}/price/{tokenAddress} for the latest or point-in-time CC price, and GET /{chain}/price/{tokenAddress}/history when you want chart data.
Transfer and treasury tracking
Sometimes you do not want the full update history. You just want asset movements.
That is where GET /{chain}/transfers/{party} comes in. It lets you focus on CC transfers, with filters such as sender vs receiver and transfer type. GET /{chain}/transfers/{party}/stats is the higher-level companion endpoint when you want totals, volume, and counterparty stats instead of the raw list.
Rewards dashboards
If you are building reporting applications around validators, apps, or other reward-bearing activity, the rewards endpoints give you a more direct surface than general update history.
Use GET /{chain}/rewards/{party} for the underlying reward events, GET /{chain}/rewards/{party}/earnings for aggregate earnings metrics, and GET /{chain}/rewards/{party}/daily when you want a daily series for charts or reporting.
Identity, directory, and name resolution
Use GET /{chain}/identity/{party} when you want a single party profile that combines network metadata with balance and activity context.
Use GET /{chain}/directory when you want to browse or search known parties on the network.
Use the ANS endpoints when your product needs human-friendly naming:
GET /{chain}/ans/{name}resolves a name to its registration details.GET /{chain}/ans/lookup/{party}performs the reverse lookup for a party.GET /{chain}/ans/availability/{name}checks whether a name is available.
Real-time Canton integrations
If you need real-time delivery, use POST /{chain}/streams to create a subscription. You can deliver updates to your own HTTPS endpoint with webhookUrl, or enable WebSocket delivery with websocketEnabled and connect to the returned websocketUrl.
Streams can stay broad, or they can be narrowed with filters. You can scope by party, by classification type, by raw DAML event shape, or by utility filters such as allCCMovements.