> ## Documentation Index > Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Initiate settlement > Create a new settlement. Validates the template and parties, then creates the settlement in the template's initial state. The settlement engine is enqueued automatically to advance through the template's action chain. The request is idempotent - sending the same idempotency_key returns the existing settlement. ## OpenAPI ````yaml https://api-staging.keystoneos.xyz/openapi.json post /v1/settlements openapi: 3.1.0 info: title: Keystone API description: Settlement orchestration API for tokenized Real-World Assets (RWAs). version: 0.1.0 servers: - url: https://api.keystoneos.xyz description: Production security: - bearerAuth: [] tags: - name: health description: Health and version checks. - name: platforms description: Register and manage your platform profile. - name: environments description: Manage platform environments (sandbox, production). - name: settlement-templates description: View and manage settlement templates. - name: settlements description: Initiate, monitor, and manage settlements. - name: sessions description: Create and manage browser-safe session tokens for frontend widgets. - name: instructions description: Submit and manage bilateral settlement instructions. - name: invitations description: Invite team members to your platform. - name: members description: Manage platform team members and roles. - name: webhooks description: Configure webhook endpoints for real-time event notifications. - name: security description: IP allowlisting and API access controls. - name: activity description: Audit trail of platform actions. - name: dashboard description: Dashboard metrics and statistics. - name: callbacks description: Provider callback handlers (internal). - name: alchemy-webhooks description: Alchemy blockchain event webhooks (internal). - name: chains description: Supported blockchain networks for settlement. - name: admin description: KeyStone internal administration endpoints. - name: admin-platforms description: Admin platform management. - name: admin-settlements description: Admin settlement oversight and intervention. - name: admin-compliance description: Admin compliance check management. - name: admin-activity description: Admin system-wide activity logs. - name: admin-webhooks description: Admin webhook diagnostics. - name: internal description: Keystone-internal worker endpoints. - name: internal-compliance description: Internal compliance engine endpoints. paths: /v1/settlements: post: tags: - settlements summary: Initiate settlement description: >- Create a new settlement. Validates the template and parties, then creates the settlement in the template's initial state. The settlement engine is enqueued automatically to advance through the template's action chain. The request is idempotent - sending the same idempotency_key returns the existing settlement. operationId: initiate_settlement_v1_settlements_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SettlementCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SettlementRead' '422': description: Validation failed (invalid template, parties, or wallet ownership). components: schemas: SettlementCreate: properties: idempotency_key: type: string maxLength: 255 minLength: 1 title: Idempotency Key template_id: anyOf: - type: string format: uuid - type: 'null' title: Template Id template_slug: anyOf: - type: string maxLength: 100 - type: 'null' title: Template Slug external_reference: anyOf: - type: string maxLength: 255 - type: 'null' title: External Reference parties: items: $ref: '#/components/schemas/SettlementPartyInput' type: array minItems: 1 title: Parties legs: items: $ref: '#/components/schemas/SettlementLegInput' type: array minItems: 1 title: Legs timeout_at: type: string format: date-time title: Timeout At type: object required: - idempotency_key - parties - legs - timeout_at title: SettlementCreate SettlementRead: properties: id: type: string format: uuid title: Id idempotency_key: type: string title: Idempotency Key platform_id: type: string format: uuid title: Platform Id environment_id: type: string format: uuid title: Environment Id template_id: type: string format: uuid title: Template Id template_version: type: integer title: Template Version external_reference: anyOf: - type: string - type: 'null' title: External Reference settlement_type: type: string title: Settlement Type parties: items: $ref: '#/components/schemas/SettlementPartyRead' type: array title: Parties legs: items: $ref: '#/components/schemas/SettlementLegRead' type: array title: Legs state: type: string title: State timeout_at: type: string format: date-time title: Timeout At created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At trade_type: anyOf: - type: string - type: 'null' title: Trade Type linked_settlement_id: anyOf: - type: string format: uuid - type: 'null' title: Linked Settlement Id coordinator: anyOf: - type: string - type: 'null' title: Coordinator coordinator_chain: anyOf: - type: string - type: 'null' title: Coordinator Chain triggered_by: anyOf: - additionalProperties: true type: object - type: 'null' title: Triggered By audit_anchor_hash: anyOf: - type: string - type: 'null' title: Audit Anchor Hash repo_terms: anyOf: - $ref: '#/components/schemas/RepoTermsRead' - type: 'null' type: object required: - id - idempotency_key - platform_id - environment_id - template_id - template_version - external_reference - settlement_type - parties - legs - state - timeout_at - created_at - updated_at title: SettlementRead SettlementPartyInput: properties: role: type: string maxLength: 100 minLength: 1 title: Role principal_id: anyOf: - type: string format: uuid - type: 'null' title: Principal Id external_reference: anyOf: - type: string maxLength: 255 pattern: ^[A-Za-z0-9._:/-]+$ - type: 'null' title: External Reference description: >- Tenant-supplied identifier for the Principal. Either this or principal_id must be set; both is allowed. Allowlist: [A-Za-z0-9._:/-]. name: anyOf: - type: string maxLength: 255 - type: 'null' title: Name wallet_address: type: string maxLength: 255 minLength: 1 title: Wallet Address chain_id: anyOf: - type: integer - type: 'null' title: Chain Id type: object required: - role - wallet_address title: SettlementPartyInput SettlementLegInput: properties: leg_type: type: string maxLength: 100 minLength: 1 title: Leg Type instrument_id: type: string maxLength: 255 minLength: 1 title: Instrument Id chain_id: anyOf: - type: integer - type: 'null' title: Chain Id token_standard: anyOf: - type: string maxLength: 50 - type: 'null' title: Token Standard quantity: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: >- ^(?!^[-+.]*$)[+-]?0*(?:\d{0,18}|(?=[\d.]{1,37}0*$)\d{0,18}\.\d{0,18}0*$) title: Quantity direction: type: string enum: - deliver - receive title: Direction party_role: type: string maxLength: 100 minLength: 1 title: Party Role recipient_party_role: anyOf: - type: string maxLength: 100 minLength: 1 - type: 'null' title: Recipient Party Role description: >- Optional explicit role of the party receiving this leg on settlement. Required for templates with >2 parties; left null for bilateral DvP (engine falls back to opposite-role inference). external_reference: anyOf: - type: string maxLength: 255 - type: 'null' title: External Reference type: object required: - leg_type - instrument_id - quantity - direction - party_role title: SettlementLegInput SettlementPartyRead: properties: id: type: string format: uuid title: Id role: type: string title: Role platform_id: type: string format: uuid title: Platform Id environment_id: type: string format: uuid title: Environment Id external_reference: anyOf: - type: string - type: 'null' title: External Reference name: anyOf: - type: string - type: 'null' title: Name wallet_address: anyOf: - type: string - type: 'null' title: Wallet Address chain_id: anyOf: - type: integer - type: 'null' title: Chain Id status: type: string title: Status confirmed_at: anyOf: - type: string format: date-time - type: 'null' title: Confirmed At wallet_address_hint: anyOf: - type: string - type: 'null' title: Wallet Address Hint counterparty_reference: anyOf: - type: string - type: 'null' title: Counterparty Reference created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - role - platform_id - environment_id - external_reference - name - wallet_address - chain_id - status - confirmed_at - wallet_address_hint - counterparty_reference - created_at - updated_at title: SettlementPartyRead SettlementLegRead: properties: id: type: string format: uuid title: Id settlement_id: type: string format: uuid title: Settlement Id leg_type: type: string title: Leg Type instrument_id: type: string title: Instrument Id chain_id: anyOf: - type: integer - type: 'null' title: Chain Id token_standard: anyOf: - type: string - type: 'null' title: Token Standard quantity: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Quantity direction: type: string title: Direction party_role: type: string title: Party Role recipient_party_role: anyOf: - type: string - type: 'null' title: Recipient Party Role status: type: string title: Status external_reference: anyOf: - type: string - type: 'null' title: External Reference deposit_secret: anyOf: - type: string - type: 'null' title: Deposit Secret deposit_key: anyOf: - type: string - type: 'null' title: Deposit Key created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - settlement_id - leg_type - instrument_id - chain_id - token_standard - quantity - direction - party_role - status - external_reference - created_at - updated_at title: SettlementLegRead RepoTermsRead: properties: id: type: string format: uuid title: Id settlement_id: type: string format: uuid title: Settlement Id tenor_days: type: integer title: Tenor Days rate_bps: type: integer title: Rate Bps haircut_bps: type: integer title: Haircut Bps margin_band_lower: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Margin Band Lower margin_band_upper: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Margin Band Upper close_leg_settlement_id: anyOf: - type: string format: uuid - type: 'null' title: Close Leg Settlement Id created_at: type: string format: date-time title: Created At updated_at: type: string format: date-time title: Updated At type: object required: - id - settlement_id - tenor_days - rate_bps - haircut_bps - margin_band_lower - margin_band_upper - close_leg_settlement_id - created_at - updated_at title: RepoTermsRead securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Auth0 JWT access token. See [Authentication](/getting-started/authentication) for details. ````