> ## 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. # Submit settlement instruction > Submit one side of a bilateral settlement instruction. If trade_reference is null, a new reference is generated (first party). If a matching pending instruction exists with the same trade_reference, automatic matching is attempted. On successful match, a settlement is created immediately. This endpoint is idempotent via the idempotency_key. ## OpenAPI ````yaml https://api-staging.keystoneos.xyz/openapi.json post /v1/instructions 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/instructions: post: tags: - instructions summary: Submit settlement instruction description: >- Submit one side of a bilateral settlement instruction. If trade_reference is null, a new reference is generated (first party). If a matching pending instruction exists with the same trade_reference, automatic matching is attempted. On successful match, a settlement is created immediately. This endpoint is idempotent via the idempotency_key. operationId: submit_instruction_v1_instructions_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstructionCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/InstructionRead' '422': description: Validation failed. components: schemas: InstructionCreate: properties: trade_reference: anyOf: - type: string maxLength: 255 - type: 'null' title: Trade Reference template_slug: type: string maxLength: 100 minLength: 1 title: Template Slug role: type: string maxLength: 100 minLength: 1 title: Role party: $ref: '#/components/schemas/InstructionPartyInput' legs: items: $ref: '#/components/schemas/InstructionLegInput' type: array minItems: 1 title: Legs timeout_at: type: string format: date-time title: Timeout At idempotency_key: type: string maxLength: 255 minLength: 1 title: Idempotency Key fee_mode: anyOf: - type: string enum: - seller_pays - buyer_pays - split - type: 'null' title: Fee Mode trade_type: anyOf: - type: string maxLength: 50 - type: 'null' title: Trade Type repo_terms: anyOf: - $ref: '#/components/schemas/RepoTermsInput' - type: 'null' type: object required: - template_slug - role - party - legs - timeout_at - idempotency_key title: InstructionCreate InstructionRead: properties: id: type: string format: uuid title: Id trade_reference: type: string title: Trade Reference status: type: string title: Status settlement_id: anyOf: - type: string format: uuid - type: 'null' title: Settlement Id template_slug: type: string title: Template Slug role: type: string title: Role party: additionalProperties: true type: object title: Party legs: items: additionalProperties: true type: object type: array title: Legs timeout_at: type: string format: date-time title: Timeout At expires_at: type: string format: date-time title: Expires At created_at: type: string format: date-time title: Created At type: object required: - id - trade_reference - status - settlement_id - template_slug - role - party - legs - timeout_at - expires_at - created_at title: InstructionRead description: >- Read schema for settlement instructions. Maps party_data/legs_data from the ORM model to party/legs in the response using validation_alias with populate_by_name so both names are accepted. InstructionPartyInput: properties: 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: - wallet_address title: InstructionPartyInput InstructionLegInput: properties: leg_type: type: string maxLength: 100 minLength: 1 title: Leg Type default: asset_delivery 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 type: object required: - instrument_id - quantity - direction title: InstructionLegInput RepoTermsInput: properties: tenor_days: type: integer maximum: 10000 exclusiveMinimum: 0 title: Tenor Days rate_bps: type: integer maximum: 1000000 minimum: 0 title: Rate Bps haircut_bps: type: integer maximum: 10000 minimum: 0 title: Haircut Bps margin_band_lower: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: >- ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,19}0*$)\d{0,10}\.\d{0,8}0*$) title: Margin Band Lower margin_band_upper: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: >- ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,19}0*$)\d{0,10}\.\d{0,8}0*$) title: Margin Band Upper type: object required: - tenor_days - rate_bps - haircut_bps - margin_band_lower - margin_band_upper title: RepoTermsInput description: |- Canonical repo terms supplied with a repo_open instruction. These map 1:1 to the `repo_terms` table columns. The repayment amount on the closing leg is derived from `tenor_days + rate_bps + opening payment-leg quantity`, so callers do not pass it explicitly. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Auth0 JWT access token. See [Authentication](/getting-started/authentication) for details. ````