Skip to main content
Settlements can also be viewed and monitored in the KeyStone Dashboard. Use the SDK for programmatic creation and automation.

​
create

Direct settlement creation when both parties are known by a single platform. 
const settlement = await client.settlements.create({
  idempotencyKey: client.generateIdempotencyKey(),
  templateSlug: "dvp-bilateral",
  externalReference: "TRADE-2026-0042",
  parties: [
    { role: "seller", externalReference: "ACC-001", name: "Securitize Fund I", walletAddress: "0xSeller..." },
    { role: "buyer", externalReference: "ACC-002", name: "Ondo Capital", walletAddress: "0xBuyer..." },
  ],
  legs: [
    { legType: "asset_delivery", instrumentId: "OUSG", quantity: "500000", direction: "deliver", partyRole: "seller" },
    { legType: "payment", instrumentId: "USDC", quantity: "502500", direction: "deliver", partyRole: "buyer" },
  ],
  timeoutAt: new Date(Date.now() + 86400000).toISOString(),
});
Direct creation vs. bilateral instructions: Use settlements.create() when your platform knows both parties upfront (single-platform use case). For cross-platform settlements - or when counterparties submit independently - use instructions.submit(). The bilateral instruction flow is the recommended approach for most integrations.

​
Parameters

FieldTypeRequiredDescription
idempotencyKeystringYesUnique key for safe retries
templateSlugstringYes*Template slug (provide slug or ID, not both)
templateIdstringYes*Template UUID
externalReferencestringNoYour internal trade reference
partiesSettlementPartyInput[]YesAll parties in the settlement
legsSettlementLegInput[]YesAll legs (asset deliveries and payments)
timeoutAtstringYesISO 8601 settlement timeout

​
SettlementPartyInput

FieldTypeRequiredDescription
rolestringYesParty role (e.g., "seller", "buyer")
externalReferencestringYesYour internal account ID
walletAddressstringYesOn-chain wallet (for compliance screening)
namestringNoDisplay name
chainIdnumberNoBlockchain network

​
SettlementLegInput

FieldTypeRequiredDescription
legTypestringYes"asset_delivery" or "payment"
instrumentIdstringYesToken address, ISIN, or currency code
quantitystringYesAmount (string for precision)
direction"deliver" | "receive"YesTransfer direction
partyRolestringYesWhich party owns this leg
chainIdnumberNoBlockchain network
tokenStandardstringNoe.g., "ERC-20", "ERC-3643"
externalReferencestringNoExternal leg reference

​
get

Fetch a settlement by ID with parties and legs. 
const settlement = await client.settlements.get("settlement-uuid");

console.log(settlement.state);              // "AWAITING_DEPOSITS"
console.log(settlement.parties.length);     // 2
console.log(settlement.legs.length);        // 2
console.log(settlement.externalReference);  // "TRADE-2026-0042"

​
SettlementRead

FieldTypeDescription
idstringSettlement UUID
stateSettlementStateCurrent lifecycle state
templateIdstringTemplate UUID
templateVersionnumberTemplate version at creation time
externalReferencestring | nullYour trade reference
partiesSettlementParty[]All parties with roles and status
legsSettlementLeg[]All legs with amounts and status
timeoutAtstringWhen the settlement times out
createdAtstringCreation timestamp
updatedAtstringLast update timestamp
parentSettlementIdstring | nullFor repo closing legs
settlementCategorystring | null"repo_open", "repo_close", or null
maturityAtstring | nullRepo maturity date
repoMetadataobject | nullRepo rate, repayment amount

​
SettlementState

INSTRUCTED, COMPLIANCE_CHECKING, COMPLIANCE_CLEARED, AWAITING_DEPOSITS, EXECUTING_SWAP, FINALIZED, ROLLED_BACK, TIMED_OUT

​
list

Paginated list with optional state filter. 
const { items, total } = await client.settlements.list({
  state: "FINALIZED",
  limit: 20,
  offset: 0,
});

for (const s of items) {
  console.log(`${s.id}: ${s.state} - ${s.externalReference}`);
}
FieldTypeDefaultDescription
stateSettlementState-Filter by state
limitnumber50Max items per page
offsetnumber0Items to skip

​
listEvents

State transition history for a settlement. 
const { items: events } = await client.settlements.listEvents("settlement-uuid");

for (const event of events) {
  console.log(`${event.fromState ?? "(initial)"} -> ${event.toState}`);
  console.log(`  At: ${event.createdAt}`);
  console.log(`  By: ${event.triggeredBy}`);
  console.log(`  Hash: ${event.contentHash}`);
}

​
SettlementEventRead

FieldTypeDescription
idstringEvent UUID
sequencenumberEvent sequence number
fromStatestring | nullPrevious state (null for initial event)
toStatestringState after this transition
triggeredBystringWhat triggered it (e.g., "system:engine", "m2m:platform")
contentHashstringSHA-256 evidence hash
createdAtstringTimestamp

​
submitComplianceDecision

Approve or reject a settlement flagged during compliance screening. 
// Approve
const settlement = await client.settlements.submitComplianceDecision(
  "settlement-uuid",
  { decision: "approve" },
);

// Reject
const settlement = await client.settlements.submitComplianceDecision(
  "settlement-uuid",
  { decision: "reject" },
);
Only applicable when the settlement is in COMPLIANCE_CHECKING state with a flagged party.

​
getRelated

Get the opening and closing legs of a repo settlement pair. 
const { opening, closing } = await client.settlements.getRelated("settlement-uuid");

if (opening) console.log(`Opening: ${opening.id} (${opening.state})`);
if (closing) console.log(`Closing: ${closing.id} (${closing.state})`);
Returns { opening: SettlementRead | null, closing: SettlementRead | null }.