Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

order list
commandorder.list
KindPublic read
NeedsMOSTRO_PUBKEY, RELAYS. No identity: the database is never opened
PublishesNothing (only relay subscriptions, with throw-away keys if a relay asks for NIP-42 auth)
Statusesok, error
Schemasschemas/order.list.input.json, schemas/order.list.output.json

Reads the node’s public order book (NIP-69 order events) from the relays and returns the orders that match the filters.

Invocation

mostro-cli --output json order list [--side buy|sell] [--currency CODE] [--status STATUS]

Replaces listorders --kind ....

Input

OptionRequiredRule
--sidenobuy or sell, any letter case. Omitted: both sides
--currencynoUppercased, otherwise used as given (no trimming or validation). Omitted: all currencies
--statusnoOne status, any letter case. Default pending (orders that can be taken). There is no “all” value

Behavior

  1. Subscribes on every configured relay to order events (kind 38383) authored by the node, tagged z=order, from the last 7 days, at most 50 per relay.
  2. Waits until every relay has sent EOSE (15 s budget). One relay failing or not finishing fails the whole read; there is never a partial success.
  3. Deduplicates events, keeps the latest event per order id, then applies the filters.
  4. Sorts by event time, newest first.

Consequences: an order not updated in the last 7 days is not listed; with many relays and busy books the 50-per-relay limit can hide older orders (snapshot.received_events tells you how much was seen). complete_history is always false.

Success data: ListData

FieldTypeMeaning
node_pubkeyhex64The node read from
filtersobjectThe normalized filters actually applied: side (buy/sell/null), currency (string or null), status (string, never null)
ordersarray of PublicOrderPossibly empty

meta.snapshot is always present on success; see Snapshot.

Outcomes

CasestatuscodeSnapshot
Read complete (even if nothing matched)okpresent
Bad optionerrorinvalid_arguments (exit 2)null
Configurationerrorconfiguration_missing, configuration_invalidnull
Cannot connecterrorrelay_connection_failednull
Relay failed or not finishederrorrelay_read_failed, read_timeoutpresent
Too many eventserrorread_limit_exceededpresent

All stages are not_applicable.

Errors

invalid_arguments, configuration_missing, configuration_invalid, relay_connection_failed, relay_read_failed, read_timeout, read_limit_exceeded, internal_error. All are safe to retry.

Warnings

invalid_event_timestamp, cleanup_incomplete.

Examples

Status filter active; relay cleanup overran its 1 s budget, which is only a warning

order.list/active_with_cleanup_warning · status ok · exit 0 · authored

mostro-cli --output json order list --status active --side buy

{
  "schema_version": "1",
  "command": "order.list",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "filters": {
      "side": "buy",
      "currency": null,
      "status": "active"
    },
    "orders": [
      {
        "id": "00000000-0000-0000-0000-000000000014",
        "side": "buy",
        "status": "active",
        "sats_amount": "120000",
        "fiat_currency": "USD",
        "fiat_amount": "100",
        "fiat_amount_min": null,
        "fiat_amount_max": null,
        "payment_method": "Zelle",
        "premium_percent": "1",
        "created_at": "2026-11-02T08:00:00Z",
        "created_at_unix": "1793606400"
      }
    ]
  },
  "error": null,
  "warnings": [
    {
      "code": "cleanup_incomplete",
      "message": "Relay cleanup did not finish within its time budget."
    }
  ],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-26T10:00:00Z",
      "until": null,
      "observed_at": "2026-11-02T10:00:03Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 2,
      "completed_relays": 2,
      "received_events": 9,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

An empty book is a success with an empty array

order.list/empty_success · status ok · exit 0 · fixture

mostro-cli --output json order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "filters": {
      "side": null,
      "currency": null,
      "status": "pending"
    },
    "orders": []
  },
  "error": null,
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-09T00:00:00Z",
      "until": null,
      "observed_at": "2026-10-16T00:00:01Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 1,
      "completed_relays": 1,
      "received_events": 0,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

Sell orders in USD; the sats amount is above 2^53, which is why amounts are strings

order.list/large_amount_success · status ok · exit 0 · fixture

mostro-cli --output json order list --side sell --currency usd

{
  "schema_version": "1",
  "command": "order.list",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "filters": {
      "side": "sell",
      "currency": "USD",
      "status": "pending"
    },
    "orders": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "side": "sell",
        "status": "pending",
        "sats_amount": "9007199254740993",
        "fiat_currency": "USD",
        "fiat_amount": "15000",
        "fiat_amount_min": null,
        "fiat_amount_max": null,
        "payment_method": "synthetic bank transfer",
        "premium_percent": "-5",
        "created_at": "2026-10-16T00:00:00Z",
        "created_at_unix": "1792108800"
      }
    ]
  },
  "error": null,
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-09T00:00:00Z",
      "until": null,
      "observed_at": "2026-10-16T00:00:01Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 1,
      "completed_relays": 1,
      "received_events": 1,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

A fixed sell order, a buy range order at market price and an order with an unrepresentable timestamp

order.list/mixed_book · status ok · exit 0 · authored

mostro-cli --output json order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "filters": {
      "side": null,
      "currency": null,
      "status": "pending"
    },
    "orders": [
      {
        "id": "00000000-0000-0000-0000-000000000011",
        "side": "sell",
        "status": "pending",
        "sats_amount": "250000",
        "fiat_currency": "EUR",
        "fiat_amount": "200",
        "fiat_amount_min": null,
        "fiat_amount_max": null,
        "payment_method": "SEPA,Revolut",
        "premium_percent": "0",
        "created_at": "2026-11-02T09:58:00Z",
        "created_at_unix": "1793613480"
      },
      {
        "id": "00000000-0000-0000-0000-000000000012",
        "side": "buy",
        "status": "pending",
        "sats_amount": "0",
        "fiat_currency": "ARS",
        "fiat_amount": "0",
        "fiat_amount_min": "10000",
        "fiat_amount_max": "50000",
        "payment_method": "MercadoPago",
        "premium_percent": "3",
        "created_at": "2026-11-02T09:30:00Z",
        "created_at_unix": "1793611800"
      },
      {
        "id": "00000000-0000-0000-0000-000000000013",
        "side": "sell",
        "status": "pending",
        "sats_amount": "0",
        "fiat_currency": "VES",
        "fiat_amount": "500",
        "fiat_amount_min": null,
        "fiat_amount_max": null,
        "payment_method": "",
        "premium_percent": "-2",
        "created_at": null,
        "created_at_unix": "-999999999999"
      }
    ]
  },
  "error": null,
  "warnings": [
    {
      "code": "invalid_event_timestamp",
      "message": "One or more event timestamps cannot be shown as a UTC date."
    }
  ],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-26T10:00:00Z",
      "until": null,
      "observed_at": "2026-11-02T10:00:03Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 2,
      "completed_relays": 2,
      "received_events": 5,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

An unparsable node key

order.list/configuration_invalid · status error · configuration_invalid · exit 1 · captured

mostro-cli --output json --mostro-pubkey not-a-key --relays wss://relay.example order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "configuration_invalid",
    "message": "The node configuration is invalid."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": null
  }
}

Neither MOSTRO_PUBKEY nor RELAYS set

order.list/configuration_missing · status error · configuration_missing · exit 1 · captured

mostro-cli --output json order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "configuration_missing",
    "message": "Required node configuration is missing."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": null
  }
}

More than 10000 unique events: rejected rather than truncated

order.list/read_limit_exceeded · status error · read_limit_exceeded · exit 1 · authored

mostro-cli --output json order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "read_limit_exceeded",
    "message": "The public order read exceeded its event limit."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-26T10:00:00Z",
      "until": null,
      "observed_at": "2026-11-02T10:00:03Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 2,
      "completed_relays": 1,
      "received_events": 10000,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

One of two relays did not finish: an error, never partial data

order.list/read_timeout · status error · read_timeout · exit 1 · fixture

mostro-cli --output json order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "read_timeout",
    "message": "The public order read did not complete before its deadline."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-09T00:00:00Z",
      "until": null,
      "observed_at": "2026-10-16T00:00:15Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 2,
      "completed_relays": 1,
      "received_events": 1,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

The only relay refuses connections

order.list/relay_connection_failed · status error · relay_connection_failed · exit 1 · captured

mostro-cli --output json --mostro-pubkey 79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798 --relays ws://127.0.0.1:1 order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "relay_connection_failed",
    "message": "A configured relay could not be connected."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": null
  }
}

A relay closed the subscription before EOSE: no partial data

order.list/relay_read_failed · status error · relay_read_failed · exit 1 · authored

mostro-cli --output json order list

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "relay_read_failed",
    "message": "A configured relay failed during the public order read."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": {
      "since": "2026-10-26T10:00:00Z",
      "until": null,
      "observed_at": "2026-11-02T10:00:03Z",
      "per_relay_limit": 50,
      "max_unique_events": 10000,
      "configured_relays": 2,
      "completed_relays": 1,
      "received_events": 3,
      "completion_policy": "all_relays_eose",
      "complete_history": false
    }
  }
}

An invalid –side value

order.list/invalid_side · status error · invalid_arguments · exit 2 · fixture

mostro-cli --output json order list --side invalid

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_arguments",
    "message": "The command arguments are invalid."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": null
  }
}

Tokens after – are not options; JSON stays selected and the stray tokens are an argument error

order.list/terminator_keeps_json · status error · invalid_arguments · exit 2 · captured

mostro-cli --output json order list -- --output human

{
  "schema_version": "1",
  "command": "order.list",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_arguments",
    "message": "The command arguments are invalid."
  },
  "warnings": [],
  "meta": {
    "publication": "not_applicable",
    "daemon_acceptance": "not_applicable",
    "persistence": "not_applicable",
    "snapshot": null
  }
}

Next

Pick an order and take it: order take-sell for a sell order, order take-buy for a buy order. Note the book shows only the public view; order info asks the node directly.