Skip to main content

​
Overview

Use the Settlement API through gRPC SettlementService to coordinate DVP settlement, exchange settlement messages over a long-lived stream, record settlement outcomes, and query settlement state and history.

​
API surface

Below are the Settlement API sections.

​
Settlement stream

SettlementStream is the core realtime RPC in this service.

​
Message Flow:

  1. The agent sends a handshake,
  2. heartbeats,
  3. preconfirmations,
  4. DVP lifecycle events, and
  5. RFQ quotes or rejections.
This is the main endpoint to document for long-running LP agents and any service that needs live settlement orchestration rather than point-in-time queries.

​
Endpoints:

EndpointUse Сase
SettlementStreamLong-lived bidirectional stream for RFQ handling and settlement
lifecycle coordination.

​
Proposal queries

Use GetPendingProposals to retrieve pending proposals for a party and GetSettlementStatus to inspect the current state of a specific settlement. The proto comments describe these as optional unary RPCs for specific operations. These endpoints are suitable for monitoring UIs, operational dashboards, and background workers that need to poll the settlement state without joining the bidirectional stream.

​
Endpoints:

EndpointUse Сase
GetPendingProposalsFetch pending settlement proposals for a party.
GetSettlementStatusCheck the current status of a settlement.

​
Preconfirmation

Use SubmitPreconfirmation when you need to send a preconfirmation outside the streaming flow. Explicitly labels it as a manual pre-confirmation path when the stream is idle. This is useful for fallback flows, operational tooling, or integrations that do not maintain a long-lived settlement stream.

​
Endpoints:

EndpointUse Сase
SubmitPreconfirmationSubmit a manual preconfirmation when not using the stream flow.

​
Disclosed contracts

Use SaveDisclosedContract to persist a disclosed contract during allocation, and use GetDisclosedContracts to retrieve disclosed contracts. Operators can access all disclosed contracts, while buyers and sellers can access their own. These endpoints are the right place to document allocation-time artifacts and settlement disclosures separately from the higher-level settlement proposal objects.

​
Endpoints:

EndpointUse Сase
SaveDisclosedContractSave a disclosed contract during allocation.
GetDisclosedContractsRetrieve disclosed contracts for the current participant or operator.

​
Recording and history

Use RecordSettlement to record a completed settlement and RecordTransaction to store a transaction in history. Use GetTransactionHistory to retrieve historical transactions, RecordSettlementEvent to append to the settlement proposal event log, and GetSettlementHistory to fetch the event history for a proposal. Settlement history is treated as an append-only event log. This part of the API is best documented as the audit and observability layer of settlement. It is useful for post-trade operations, internal reconciliation, and external status reporting.

​
Endpoints:

EndpointUse Сase
RecordSettlementRecord a completed settlement.
RecordTransactionRecord a transaction in the settlement history.
GetTransactionHistoryRetrieve historical settlement-related transactions.
RecordSettlementEventAppend an event to the settlement proposal history log.

​
Proposal lifecycle

Use UpdateProposalStatus to move a proposal through its lifecycle, GetSettlementProposalById to fetch proposal details by ID, and CancelSettlement to cancel a settlement before execution.UpdateProposalStatus is operator-only and is described CancelSettlement as available to the buyer or seller before settlement execution. This is the lifecycle-management part of the service and is the section to document for operational controls, dispute handling, and manual intervention flows.

​
Endpoints:

EndpointUse Сase
UpdateProposalStatusUpdate the proposal status to operator-only.
GetSettlementProposalByIdFetch a settlement proposal by ID.
CancelSettlementCancel a settlement before execution.

​
Example flow

A typical settlement flow looks like this:
  1. Open SettlementStream and complete the handshake.
  2. Receive RFQ requests or settlement proposals from the server.
  3. Send preconfirmations and other settlement lifecycle messages as the flow progresses.
  4. Record outcomes and events through the unary recording endpoints when needed.
  5. Query status or proposal history through the history and lifecycle endpoints.
The agent opens this stream when [liquidity_provider] is configured in agent.toml.