Powered by

Strategy Server API

The Strategy Server exposes two HTTP-based APIs: a REST API for managing strategies and reading metrics, and a WebSocket API for real-time access to message channels. The CryptoStruct Backend uses both, and external automation can use them too.

REST API

The REST API supports:

  • Creating and deleting strategy instances.
  • Starting and stopping strategy instances.
  • Retrieving information about installed strategies.
  • Retrieving information about running instances.
  • Publishing messages to message channels.
  • Reading metrics about strategies, market data, and the JVM.

It's used by the CryptoStruct Backend; custom automation tooling can use it directly.

Interactive API explorer

The Strategy Server serves an interactive API explorer in the browser:

http://<strategy-server>:8000

The explorer shows:

  • All endpoints with full documentation.
  • Request and response schemas.
  • An in-browser request tester.
  • Example payloads.

Common endpoints

Method Endpoint Description
GET /api/v1/strategy List installed strategies
GET /api/v1/strategy/instance List created instances
GET /api/v1/strategy/instance/status Status of all instances
POST /api/v1/strategy/instance Create strategy instance
POST /api/v1/strategy/instance/{instanceId}/start Start instance
POST /api/v1/strategy/instance/{instanceId}/stop Stop instance
POST /api/v1/strategy/instance/{instanceId}/delete Delete instance

The full set of endpoints, including bulk operations and reconfigure operations, is documented in the in-process API explorer.

Message-channel REST endpoint

REST exposes a single endpoint for broadcasting a message on a channel from outside:

curl -X POST "http://localhost:8000/api/v1/channel/testchannel/send?origin=myapplication" \
  -H "accept: application/json" \
  -H "Content-Type: text/plain" \
  -d '{"value":"7.3"}'
Parameter Location Type Description
channelName URL path string Name of the target channel
origin Query string string Identifier for the message sender
Request body Body string Plain text message content

Use cases:

  • Parameter updates to running strategies.
  • External signals or alerts.
  • Configuration changes.
  • Infrequent data feeds.

Message-channel WebSocket API

The WebSocket API gives bidirectional, real-time access to message channels. External applications can:

  • Subscribe to channels and receive every message published on them.
  • Publish high-frequency data to channels.
  • Build custom integrations and monitoring tools.

Connecting

WebSocket endpoint:

ws://<strategy-server>:8000/ws/v1

Default port 8000 (shared with REST).

Requests

Messages from client to server are JSON objects.

Login

Required before any other operation.

{
  "op": "login",
  "origin": "my_client"
}
Field Type Description
op string Operation: "login"
origin string Unique identifier for this client (will be used as message origin) 
{
  "op": "login",
  "origin": "my_client",
  "result": "succeed"
}
 
{
  "op": "login",
  "origin": "my_client",
  "error": "already logged in"
}

Subscribe to channel

Subscribe to receive messages published on a channel.

{
  "op": "subscribe",
  "channel": "signal_channel"
}
Field Type Description
op string Operation: "subscribe"
channel string Channel name 
{
  "op": "subscribe",
  "channel": "signal_channel",
  "result": "succeed"
}
 
{
  "op": "subscribe",
  "channel": "signal_channel",
  "error": "not logged in"
}

Unsubscribe from channel

Stop receiving messages from a channel.

{
  "op": "unsubscribe",
  "channel": "signal_channel"
}
Field Type Description
op string Operation: "unsubscribe"
channel string Channel name 
{
  "op": "unsubscribe",
  "channel": "signal_channel",
  "result": "succeed"
}

Publish message

Broadcast a message on a channel.

{
  "op": "publish",
  "channel": "signal_channel",
  "message": "Hello, strategies!"
}
Field Type Description
op string Operation: "publish"
channel string Channel name
message string Message content (any string) 
{
  "op": "publish",
  "channel": "signal_channel",
  "error": "not logged in"
}

Events

Messages from server to client.

Event message

Sent when a message is published on a subscribed channel.

{
  "op": "event",
  "channel": "signal_channel",
  "origin": "strategy_instance_1",
  "message": "Signal data here"
}
Field Type Description
op string Operation: "event"
channel string Channel name
origin string Message sender (strategy instance name or client origin)
message string Message content

Error message

Sent when the client sends an invalid message.

{
  "op": "error",
  "channel": "signal_channel",
  "error": "invalid json"
}
Field Type Description
op string Operation: "error"
channel string Channel name (if applicable)
error string Error description

Kafka integration

Channels can be wired to Kafka topics for advanced use cases.

Configuration

Configure Kafka in the Strategy Server config file:

{
  "kafka_servers": [
    "broker1:9092",
    "broker2:9092"
  ],
  "kafka_stop_on_error": true,
  "kafka_topics": [
    "readOnlyTopic:r",
    "writeOnlyTopic:w",
    "readWriteTopic:rw",
    "defaultTopic"
  ]
}

Configuration fields:

Field Description
kafka_servers List of Kafka broker addresses
kafka_stop_on_error If true, stop strategies on Kafka write failure
kafka_topics List of topics with permissions

Topic permissions:

  • r: read-only (consume from Kafka).
  • w: write-only (produce to Kafka, default).
  • rw: read and write.

Channel data types

For writing to Kafka:

  • Channel type must be String or KafkaMessage.

  • String channels: record key is the process ID (or null if disabled).

  • KafkaMessage channels: key and value are specified explicitly.

For reading from Kafka:

  • Channel type must be KafkaMessage.

Kafka record headers

Every record written to Kafka carries:

Header Description
CS_ORIGIN Message origin (strategy instance name or API client)
CS_PROCESS_ID Strategy Server process ID

KafkaMessage type

For programmatic access from a strategy, see SDK - Message Channels.

See also