Sandbox and authentication

Endpoint

Environment	URL
Sandbox	`wss://partners-rt-gw.sandbox.securitize.io/v1/market-maker/stream`

TLS only. A plain ws:// connection is never answered: it hangs until your client gives up, with no error to read. Check the scheme before you debug anything else.

Production uses the same messages at a production URL, arranged with Securitize once your integration passes the go-live checklist.

Keys

You sign with an Ed25519 keypair. You register its public key with Securitize; the private key never leaves your systems, and nothing secret crosses the wire in either direction. Any Ed25519 keypair works, whatever chain your CETs are minted on; a Solana keypair is one. Prefer a dedicated keypair over one that also holds assets.

Generate a keypair

With OpenSSL, and Python’s base58 package (pip install base58) to print the keys the way the API uses them:

openssl genpkey -algorithm ed25519 -out private.pem

# Public key, base58: the one you register with Securitize
openssl pkey -in private.pem -pubout -outform DER | tail -c 32 | python3 -c 'import sys,base58;print(base58.b58encode(sys.stdin.buffer.read()).decode())'

# Private key, base58: what your client signs with. Keep it secret
openssl pkey -in private.pem -outform DER | tail -c 32 | python3 -c 'import sys,base58;print(base58.b58encode(sys.stdin.buffer.read()).decode())'

Send Securitize the base58 public key, the wallet that should receive your CETs, and whether the key trades or is read-only. To fund your cash with crypto, also send the wallets you will send USDC from. Never send the private key. Once the key is registered, the examples in Open a session connect with the private key in CET_SIGNING_KEY. To rotate, register another public key. Several can be active at once, so you can move to the new key and then ask Securitize to retire the old one, with no coordinated cutover. A key can be registered read-only: its session gets every read and every push, and place_order and cancel_order answer NOT_PERMITTED. Use one for monitoring and reconciliation, so the systems that only read never hold a key that can trade.

Signing

hello, place_order and cancel_order carry a timestamp and a signature:

signature = base58( Ed25519-Sign( privateKey,
                                  timestamp + "." + type + "." + payloadBytes ) )

payloadBytes are the exact bytes of payload as they go on the wire. The server verifies the payload it received, never a re-serialisation of it. Key order and whitespace are yours to choose, as long as what you sign is what you send: serialise the payload once, sign that string, and put the same string in the frame. This is the most common way a signed integration fails.
timestamp is Unix seconds, within 30 seconds of the server clock. Keep NTP running: a drifted clock has every signed message refused with TIMESTAMP_OUT_OF_WINDOW. welcome and pong carry serverTime to check yours against.
type is part of the signed text, so a signature made for one message cannot be lifted onto another.

Signed	Unsigned
`hello`, `place_order`, `cancel_order`, `submit_crypto_funding`	`get_symbols`, `get_redemption_address`, `get_redemption_balance`, `get_redemption_balances`, `get_order`, `get_mints`, `get_burns`, `get_cash_balance_v2`, `get_cash_movements`, `get_crypto_funding`, `ping`

Reads and the heartbeat ride on the session hello opens; everything that moves shares, CETs or cash is signed. Most reads are also served over HTTP without a session, each request signed with the same key: see Reads over HTTP. The sandbox-only sandbox_deposit and sandbox_withdraw are signed the same way.

Open a session

Connect, send a signed hello within 10 seconds, wait for welcome, then send ping every heartbeatSeconds. Both examples read the private key, base58, from an environment variable; a 64-byte Solana secret key works too, since its first 32 bytes are the Ed25519 seed.

// npm install ws @noble/ed25519 bs58
import WebSocket from 'ws';
import * as ed from '@noble/ed25519';
import bs58 from 'bs58';
import { randomUUID } from 'node:crypto';

const URL = 'wss://partners-rt-gw.sandbox.securitize.io/v1/market-maker/stream';
const privateKey = bs58.decode(process.env.CET_SIGNING_KEY).slice(0, 32);
const publicKey = bs58.encode(await ed.getPublicKeyAsync(privateKey));

// A requestId of at most 32 characters is echoed intact: a UUID without its hyphens.
const requestId = () => randomUUID().replaceAll('-', '');

// The payload is serialised once: the same string is signed and sent.
async function signedFrame(type, payload) {
  const payloadJson = JSON.stringify(payload);
  const timestamp = Math.floor(Date.now() / 1000);
  const signed = new TextEncoder().encode(`${timestamp}.${type}.${payloadJson}`);
  const signature = bs58.encode(await ed.signAsync(signed, privateKey));
  return `{"type":${JSON.stringify(type)},"requestId":"${requestId()}","timestamp":${timestamp},"payload":${payloadJson},"signature":"${signature}"}`;
}

const ws = new WebSocket(URL);
ws.on('open', async () => ws.send(await signedFrame('hello', { publicKey, nonce: randomUUID() })));
ws.on('message', (data) => {
  const frame = JSON.parse(data);
  if (frame.type === 'welcome') {
    setInterval(() => ws.send(JSON.stringify({ type: 'ping', requestId: requestId() })), frame.payload.heartbeatSeconds * 1000);
  }
  console.log(frame.type, frame.requestId ?? '', JSON.stringify(frame.payload));
});
ws.on('close', (code) => console.log('closed', code));

# pip install websockets pynacl base58
import asyncio, json, os, time, uuid

import base58
import websockets
from nacl.signing import SigningKey

URL = "wss://partners-rt-gw.sandbox.securitize.io/v1/market-maker/stream"
signing_key = SigningKey(base58.b58decode(os.environ["CET_SIGNING_KEY"])[:32])
public_key = base58.b58encode(bytes(signing_key.verify_key)).decode()


def signed_frame(type_, payload):
    payload_json = json.dumps(payload, separators=(",", ":"))  # serialised once: signed and sent as is
    timestamp = int(time.time())
    signed = f"{timestamp}.{type_}.{payload_json}".encode()
    signature = base58.b58encode(signing_key.sign(signed).signature).decode()
    return (f'{{"type":{json.dumps(type_)},"requestId":"{uuid.uuid4().hex}","timestamp":{timestamp},'
            f'"payload":{payload_json},"signature":"{signature}"}}')


async def heartbeat(ws, seconds):
    while True:
        await asyncio.sleep(seconds)
        await ws.send(json.dumps({"type": "ping", "requestId": uuid.uuid4().hex}))


async def main():
    async with websockets.connect(URL) as ws:
        await ws.send(signed_frame("hello", {"publicKey": public_key, "nonce": str(uuid.uuid4())}))
        welcome = json.loads(await ws.recv())
        if welcome["type"] != "welcome":
            raise RuntimeError(welcome)
        asyncio.create_task(heartbeat(ws, welcome["payload"]["heartbeatSeconds"]))
        async for raw in ws:
            frame = json.loads(raw)
            print(frame["type"], frame.get("requestId", ""), frame.get("payload"))


asyncio.run(main())

welcome means you are connected. An error with SIGNATURE_INVALID means the signature or the key (below).

Limits

What	Limit	Past it
Time from connecting to `hello`	10 seconds	The socket is closed (`4001`)
Clock difference on a signed message	30 seconds	`TIMESTAMP_OUT_OF_WINDOW`; the socket stays open
Heartbeat	`ping` every 10 seconds	A socket quiet for 3 minutes is closed (`4008`)
Frame size	64 KB	The socket is closed (`1009`), without an `error` first
Sessions per socket	One	A second `hello` answers `MALFORMED`; the first session stands

One socket is one session. A second connection opens a second session, not a second channel on the first.

Reconnecting

Reconnect on any close or dropped connection, including 1006 (closed without a close frame), with backoff, never in a tight loop, and open a new session. A release restarts the service and closes every socket with 1001. Updates sent while you were disconnected are not replayed: read back every order you still hold as working with get_order. See Track, cancel and reconcile orders.

When the session does not open

What you see	Meaning
The connection hangs, with nothing to read	`ws://` instead of `wss://`
`error` `SIGNATURE_INVALID`, then the socket closes	The signature does not verify, or the public key is not registered; the two are not distinguished. Check that you sign the exact payload string you send
`error` `TIMESTAMP_OUT_OF_WINDOW`, the socket stays open	Your clock is more than 30 seconds off. Fix NTP; reconnecting does not help
`error` `UPSTREAM_UNAVAILABLE`, the socket stays open	The key could not be checked at that moment. Send a new `hello`, with a new `nonce`, on the same socket
`error` `UNAUTHENTICATED`, then the socket closes	A message other than `hello` was sent before `welcome`
The socket closes about 10 seconds after connecting	No `hello` arrived

How sandbox behaves

Sandbox sends orders to the broker’s simulator, which executes every order at once, at whatever limit price you name, even one far from the market. That makes the whole lifecycle testable without a live market. Calibrate nothing on it:

A LIMIT order never rests. It fills at your price at once. In production it rests until the market reaches it.
Cancelling never succeeds. Every order has filled before the cancellation arrives, so every cancel_order answers ORDER_NOT_CANCELLABLE. In production, PENDING_CANCEL and CANCELLED are ordinary.
Before the market opens, an order priced more than 2% from the last price is refused. During market hours the simulator fills it regardless.
Fills come 100 shares at a time. A 250-share order arrives as three executions and three trade_updated frames, and usually mints more than once.
References must change between runs. An externalRef you already used is refused as a duplicate, including the ones in these docs.
You fund your own cash. The sandbox-only sandbox_deposit and sandbox_withdraw move USD into and out of it. See Sandbox funding.

Get started

Sandbox only

Guides

Concepts

Help

API reference

Endpoint

Keys

Generate a keypair

Signing

Open a session

Limits

Reconnecting

When the session does not open

How sandbox behaves