Submit settlement instruction

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    template_slug: '<string>',
    role: '<string>',
    party: {
      external_reference: '<string>',
      wallet_address: '<string>',
      name: '<string>',
      chain_id: -1
    },
    legs: [
      {
        instrument_id: '<string>',
        quantity: 1,
        leg_type: 'asset_delivery',
        chain_id: 123,
        token_standard: '<string>'
      }
    ],
    timeout_at: '2023-11-07T05:31:56Z',
    idempotency_key: '<string>',
    trade_reference: '<string>',
    trade_type: '<string>',
    repo_terms: {
      tenor_days: 123,
      rate_bps: 500000,
      haircut_bps: 5000,
      margin_band_lower: 1,
      margin_band_upper: 1
    }
  })
};

fetch('https://api-staging.keystoneos.xyz/v1/instructions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api-staging.keystoneos.xyz/v1/instructions"

payload = {
    "template_slug": "<string>",
    "role": "<string>",
    "party": {
        "external_reference": "<string>",
        "wallet_address": "<string>",
        "name": "<string>",
        "chain_id": -1
    },
    "legs": [
        {
            "instrument_id": "<string>",
            "quantity": 1,
            "leg_type": "asset_delivery",
            "chain_id": 123,
            "token_standard": "<string>"
        }
    ],
    "timeout_at": "2023-11-07T05:31:56Z",
    "idempotency_key": "<string>",
    "trade_reference": "<string>",
    "trade_type": "<string>",
    "repo_terms": {
        "tenor_days": 123,
        "rate_bps": 500000,
        "haircut_bps": 5000,
        "margin_band_lower": 1,
        "margin_band_upper": 1
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api-staging.keystoneos.xyz/v1/instructions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_slug": "<string>",
  "role": "<string>",
  "party": {
    "external_reference": "<string>",
    "wallet_address": "<string>",
    "name": "<string>",
    "chain_id": -1
  },
  "legs": [
    {
      "instrument_id": "<string>",
      "quantity": 1,
      "leg_type": "asset_delivery",
      "chain_id": 123,
      "token_standard": "<string>"
    }
  ],
  "timeout_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>",
  "trade_reference": "<string>",
  "trade_type": "<string>",
  "repo_terms": {
    "tenor_days": 123,
    "rate_bps": 500000,
    "haircut_bps": 5000,
    "margin_band_lower": 1,
    "margin_band_upper": 1
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "trade_reference": "<string>",
  "status": "<string>",
  "settlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "template_slug": "<string>",
  "role": "<string>",
  "party": {},
  "legs": [
    {}
  ],
  "timeout_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z"
}

Instructions

Submit settlement instruction

Submit one side of a pre-agreed bilateral settlement instruction. If trade_reference is null, a new unguessable reference is generated (first party); sharing it out of band is what lets the counterparty match, including from another platform environment of the same type (development, staging, production) - environments of different types never match. A trade_reference you choose yourself pairs only within your own environment - cross-platform matching always uses the generated reference. If a pending counterpart instruction exists within that matching scope, KeyStone confirms the two sides agree; on confirmation, a settlement is created immediately. This endpoint is idempotent via the idempotency_key.

POST

instructions

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    template_slug: '<string>',
    role: '<string>',
    party: {
      external_reference: '<string>',
      wallet_address: '<string>',
      name: '<string>',
      chain_id: -1
    },
    legs: [
      {
        instrument_id: '<string>',
        quantity: 1,
        leg_type: 'asset_delivery',
        chain_id: 123,
        token_standard: '<string>'
      }
    ],
    timeout_at: '2023-11-07T05:31:56Z',
    idempotency_key: '<string>',
    trade_reference: '<string>',
    trade_type: '<string>',
    repo_terms: {
      tenor_days: 123,
      rate_bps: 500000,
      haircut_bps: 5000,
      margin_band_lower: 1,
      margin_band_upper: 1
    }
  })
};

fetch('https://api-staging.keystoneos.xyz/v1/instructions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api-staging.keystoneos.xyz/v1/instructions"

payload = {
    "template_slug": "<string>",
    "role": "<string>",
    "party": {
        "external_reference": "<string>",
        "wallet_address": "<string>",
        "name": "<string>",
        "chain_id": -1
    },
    "legs": [
        {
            "instrument_id": "<string>",
            "quantity": 1,
            "leg_type": "asset_delivery",
            "chain_id": 123,
            "token_standard": "<string>"
        }
    ],
    "timeout_at": "2023-11-07T05:31:56Z",
    "idempotency_key": "<string>",
    "trade_reference": "<string>",
    "trade_type": "<string>",
    "repo_terms": {
        "tenor_days": 123,
        "rate_bps": 500000,
        "haircut_bps": 5000,
        "margin_band_lower": 1,
        "margin_band_upper": 1
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api-staging.keystoneos.xyz/v1/instructions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_slug": "<string>",
  "role": "<string>",
  "party": {
    "external_reference": "<string>",
    "wallet_address": "<string>",
    "name": "<string>",
    "chain_id": -1
  },
  "legs": [
    {
      "instrument_id": "<string>",
      "quantity": 1,
      "leg_type": "asset_delivery",
      "chain_id": 123,
      "token_standard": "<string>"
    }
  ],
  "timeout_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>",
  "trade_reference": "<string>",
  "trade_type": "<string>",
  "repo_terms": {
    "tenor_days": 123,
    "rate_bps": 500000,
    "haircut_bps": 5000,
    "margin_band_lower": 1,
    "margin_band_upper": 1
  }
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "trade_reference": "<string>",
  "status": "<string>",
  "settlement_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "template_slug": "<string>",
  "role": "<string>",
  "party": {},
  "legs": [
    {}
  ],
  "timeout_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Auth0 JWT access token. See Authentication for details.

Body

application/json

template_slug

string

required

Required string length: 1 - 100

role

string

required

Required string length: 1 - 100

party

InstructionPartyInput · object

required

The submitting party of an instruction.

Show child attributes

legs

InstructionLegInput · object[]

required

Minimum array length: 1

Show child attributes

timeout_at

string<date-time>

required

idempotency_key

string

required

Your key for safe retries, unique within the environment. A retry with the same key returns the existing resource. Keys starting with 'match-' are reserved for keys KeyStone derives and are refused.

Required string length: 1 - 255

trade_reference

string | null

The counterparties' shared reference for the pre-agreed trade. A reference you choose yourself matches only within your own environment; cross-platform matching uses the reference KeyStone generates when this field is null.

Maximum string length: 255

trade_type

string | null

Maximum string length: 50

repo_terms

RepoTermsInput · object | null

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.

Show child attributes

Response

Successful Response

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.

string<uuid>

required

trade_reference

string

required

status

string

required

settlement_id

string<uuid> | null

required

template_slug

string

required

role

string

required

party

Party · object

required

legs

Legs · object[]

required

timeout_at

string<date-time>

required

expires_at

string<date-time>

required

created_at

string<date-time>

required

Overview

Platforms

Environments

Settlement Templates

Instructions

Settlements

Team Management

Webhooks

Security

Activity

Chains

Submit settlement instruction

Authorizations

Body

Response