How Agents Use the SDK and API
Agents connect to Silvana using SDK, which wraps the platform’s API. The API itself defines what actions are possible such as placing or cancelling an order, while the SDK gives developers a convenient way to call these actions without dealing with low-level details like network protocols. When an agent starts up, it uses the SDK to connect to the Silvana backend via secure communication (gRPC). The SDK handles authentication (usually via a JWT token), formats requests properly, and manages streaming connections to receive real-time updates. This SDK wraps a set of API calls that agents use to:- Authenticate;
- Submit or cancel orders;
- Read orderbook and market data;
- Subscribe to streaming updates;
- Monitor and respond to settlements.
Execution API
The following operations are central to how execution is observed and driven:| Purpose | Operations |
|---|---|
| Place/cancel orders | submitOrder, cancelOrder |
| Read book and orders | getOrderbookDepth, getOrders, getOrderHistory |
| Real-time execution feedback | subscribeOrderbook, subscribeOrders |
| Settlement lifecycle | getSettlementProposals, getSettlements, subscribeSettlements |
| Markets and instruments | getMarkets, getInstruments, getMarketData |
Settlement API
Below is the key settlement API:Bidirectional Stream
| Method | Purpose |
|---|---|
settlementStream(messages) | Canton node sends an async stream of CantonToServerMessage and receives a stream of ServerToCantonMessage. The server uses this to send handshakes, preconfirmation requests, DvP creation/acceptance/allocation commands, status updates, and errors. The node responds with handshake acks, preconfirmation decisions, DvP reports, and heartbeats. This is the main channel for driving DvP. |
Proposals and Status
| Method | Purpose |
|---|---|
getPendingProposals(params) | Get pending settlement proposals for a partyId. Used by a settlement agent to discover work. |
getSettlementProposalById(params) | Fetch a single proposal by ID (e.g. to inspect details before deciding). |
getSettlementStatus(params) | Query current status of a settlement (e.g. stage, DvP step status). |
updateProposalStatus(params) | Update proposal status (operator only; e.g. mark failed or cancelled). |
Preconfirmation
| Method | Purpose |
|---|---|
submitPreconfirmation(params) | Submit a preconfirmation decision (accept/reject) when not using the stream. Often preconfirmation is sent via the bidirectional stream instead. |
Disclosed Contracts
| Method | Purpose |
|---|---|
saveDisclosedContract(params) | Buyer or seller saves a disclosed contract during allocation. |
getDisclosedContracts(params) | Retrieve disclosed contracts for a proposal (operator gets all; buyer/seller get their own). |
Recording and History
| Method | Purpose |
|---|---|
recordSettlementEvent(params) | Record a settlement event (e.g. DvP step started/completed, error) for a proposal. Used for audit and DvP flow tracking. |
getSettlementHistory(params) | Get event history for a proposal (filter by event type, result, pagination). |
recordSettlement(params) | Called after successful on-chain DvP settle: updates the proposal and creates the settlements record. Typically used by the settlement operator. |
recordTransaction(params) | Record a transaction (type, party, result, DAML template/choice, etc.) for history. |
getTransactionHistory(params) | Query transaction history with filters (party, type, proposal, result). |