Settlement Status

Per-match settlement outcomes and on-chain signatures for one engine batch ID.

curl --request GET \
  --url https://api.darknyx.example.com/settlement/status/{batch_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.darknyx.example.com/settlement/status/{batch_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.darknyx.example.com/settlement/status/{batch_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.darknyx.example.com/settlement/status/{batch_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.darknyx.example.com/settlement/status/{batch_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.darknyx.example.com/settlement/status/{batch_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "batch_id": 123,
  "jobs": [
    {
      "batch_id": 123,
      "match_idx": 123,
      "stage": "queued",
      "outcome": {
        "kind": "pending",
        "signature": "<string>",
        "slot": 123,
        "reconciled_from_consumed_pdas": true,
        "reason": "settlement_rejected"
      },
      "created_at_ms": 123,
      "last_transition_at_ms": 123,
      "failed_reason": "rpc_unavailable",
      "lock_buyer_sig": "<string>",
      "lock_seller_sig": "<string>",
      "verify_sig": "<string>",
      "settle_sig": "<string>",
      "close_sig": "<string>"
    }
  ]
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

TL;DRGET /settlement/status/{batch_id} returns every per-match job in a settlement batch. A match can be pending, confirmed, rejected, or ambiguous independently of its siblings. This is an authenticated operational/debug surface; trader clients should treat the orders and fills streams as their primary lifecycle.

GET /settlement/status/{batch_id}

batch_id is an unsigned integer local to the running engine. It is not an on-chain identifier and the order-read response does not promise a batch-id field. Use this endpoint when an operator or diagnostic response has supplied a known batch handle. The engine retains a bounded recent window of terminal batches, so 404 may mean the handle is unknown or has aged out; use the orders and fills streams as the trader-facing lifecycle source. Authenticated with a bearer token:

curl -s "$GATEWAY/settlement/status/$BATCH_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

{
  "batch_id": 42,
  "jobs": [
    {
      "batch_id": 42,
      "match_idx": 0,
      "stage": "done",
      "outcome": {
        "kind": "confirmed",
        "signature": "5xQ…",
        "slot": 309482113,
        "reconciled_from_consumed_pdas": false
      },
      "created_at_ms": 1784271000000,
      "last_transition_at_ms": 1784271002880,
      "lock_buyer_sig": "2aB…",
      "lock_seller_sig": "3cD…",
      "verify_sig": "4eF…",
      "settle_sig": "5xQ…"
    }
  ]
}

Each job has a match_idx, current stage, independent outcome, timestamps, and whichever Solana signatures have confirmed so far. Optional fields are omitted until available.

Stages

stage is one of queued, locking_notes, proving, verifying, settling, closing, done, or failed. A done match has confirmed even when the shared marker has not yet been reclaimed; marker close is asynchronous rent cleanup, not part of trade finality.

Outcomes

`outcome.kind`	Meaning
`pending`	No final per-match result yet.
`confirmed`	The settle transaction confirmed, or finalized consumed-note accounts proved it landed.
`rejected`	A definitive error made the match terminal.
`ambiguous`	RPC evidence is inconclusive; the engine keeps the match reserved while reconciling or safely redriving it.

Do not infer that every match succeeded from a batch-wide stage. Inspect every job. The user-facing order lifecycle commits a fill only for confirmed; a definitive failure emits settlement_failed and requires a fresh order after the input lock expires. See Settlement for the finality model.

Authorizations

Authorization

string

header

required

Short-lived (≤ 1h) bearer token from POST /auth/token.

Expiry is EXACT — there is no grace period past expires_in, on REST or on the streaming transport. Refresh on a margin.

A structurally valid, unexpired token is still refused when it has been revoked (401), when the operator has invalidated the tokens the account was holding (401), or when the account is suspended (403). Suspension also blocks issuing a new one, so re-authenticating does not clear it.

Path Parameters

batch_id

integer<uint64>

required

Response

Settlement status.

batch_id

integer<uint64>

required

jobs

object[]

required

Per-match status in match-index order. Confirmed siblings can reach done while an ambiguous sibling remains settling and redrives.

Show child attributes

⌘I

Per-match settlement outcomes and on-chain signatures for one engine batch ID.

curl --request GET \
  --url https://api.darknyx.example.com/settlement/status/{batch_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.darknyx.example.com/settlement/status/{batch_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.darknyx.example.com/settlement/status/{batch_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.darknyx.example.com/settlement/status/{batch_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.darknyx.example.com/settlement/status/{batch_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.darknyx.example.com/settlement/status/{batch_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "batch_id": 123,
  "jobs": [
    {
      "batch_id": 123,
      "match_idx": 123,
      "stage": "queued",
      "outcome": {
        "kind": "pending",
        "signature": "<string>",
        "slot": 123,
        "reconciled_from_consumed_pdas": true,
        "reason": "settlement_rejected"
      },
      "created_at_ms": 123,
      "last_transition_at_ms": 123,
      "failed_reason": "rpc_unavailable",
      "lock_buyer_sig": "<string>",
      "lock_seller_sig": "<string>",
      "verify_sig": "<string>",
      "settle_sig": "<string>",
      "close_sig": "<string>"
    }
  ]
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

{
  "code": 1102,
  "message": "trading_key_signature does not verify against the canonical body"
}

Getting Started

System

Account

Instruments

Orders

Settlement

Tree

WebSocket

Settlement Status

GET /settlement/status/{batch_id}

Response

Stages

Outcomes

Authorizations

Path Parameters

Response

​GET /settlement/status/{batch_id}

​Response

​Stages

​Outcomes

Authorizations

Path Parameters

Response

GET /settlement/status/{batch_id}

Response

Stages

Outcomes