Market Maker Beta Quickstart
This is the private-beta integration path a market maker should start with. It separates what is live and tested from routes that are reserved for operations, onboarding, or later contract rollout.
Before implementing, review Live Verified Beta. It shows the latest live BSL/FIX conformance status, credential boundary checks, and public-internet sample timings.
After creating an institutional_agent, call
GET /api/v1/bsl/connectivity or GET /api/v1/fix/connectivity. The bundle
returns the BSL Direct TCP host/port/SNI, FIX endpoint contract,
TargetCompID(56), and stable SenderCompID(49) values. Do not guess FIX
CompIDs or raw TCP ports.
Do not start with /api/v1/institutional/*. Those routes are account/reporting
and provisioning surfaces, not the market-maker order-entry path.
For the first funded beta quote, use BSL compact HTTP and prove private
reconciliation. Direct TCP is the latency lane after account-level conformance,
not the first proof. Compact HTTP is available through POST /api/order-entry/binary
or the direct trading-plane compatibility route POST /api/v1/mm/orders/batch.bin.
The canonical compact HTTP route is POST /api/v1/bsl/orders/compact; use it
with institutional_agent HMAC auth or a provisioned lane key from the
connectivity bundle.
What is verified in beta
| Flow | Status | Notes |
|---|---|---|
| Public status and markets | Live | Use the public HTTP and WebSocket surfaces. |
| BSL limit metadata | Live | GET /api/v1/bsl/limits returns the BSL contract and rate envelope. |
| BSL execution-stream metadata | Live | GET /api/v1/bsl/executions describes stream and replay paths. |
| BSL sessions and quote obligations | Live metadata | Session list and obligation config may be empty for accounts without provisioned obligations. |
| BSL Direct TCP contract | Live contract | Use bslTcp from the connectivity bundle after HTTP BSL quote/reconciliation conformance; native TCP/TLS, not HTTPS. |
| Signed compact order submit | Live on direct institutional binary route and compatibility paths | Use POST /api/order-entry/binary first, or /api/v1/mm/orders/batch.bin where provisioned, with x-bsl-result-mode: ack and x-senticore-response-mode: detailed. |
| FIX order entry | Live with institutional_agent | Raw TCP/TLS, direct host/port from connectivity bundle, HMAC Logon. |
| Private execution gap-fill | Protected | Requires an account/private session token or provisioned BSL machine credential. |
BSL full result mode | Contract in progress | Do not rely on it as your production terminal-result path until it is enabled and tested for your account. |
| Cancel-on-disconnect | Provisioned control | Configure and test with operations before using it for unattended quoting. |
Credentials
There is no shared public BSL key.
| Credential | Use |
|---|---|
| Wallet or delegated signature | Required inside every mutating signed action. |
| Optional order-entry lane key | Dedicated low-latency lane and rate tier, provisioned by operations or builder onboarding. |
institutional_agent HMAC credential | FIX Logon, BSL order-entry machine auth, protected BSL reads, drop-copy, and business-line machine access. |
api_agent credential | Standard HTTP bot/private-read access, not the preferred FIX/BSL credential. |
Base signed submit can work without a lane key when beta policy allows it, but
production market makers should still use provisioned machine credentials and
rate tiers. Use institutional_agent for BSL/FIX access. Keep owner wallet
keys out of trading systems.
The optional order-entry lane key is not the FIX credential. FIX uses the
institutional_agent HMAC tuple and the connectivity bundle's CompIDs.
BSL Direct TCP
The native low-latency path is raw TCP/TLS:
host/port/tlsSni: from /api/v1/bsl/connectivity.bslTcp
protocol: senticore-bsl-tcp-v2
handshake: 48 bytes
message header: u32_le kind + u32_le payload_len
compact action frame: 192 bytes
Use BSL Direct TCP for the full protocol and SDK handshake examples.
Compact HTTP request
The live beta compact payload is SDK JSON encoded as bytes:
{"version":1,"actions":[...],"idempotencyKey":"quote-refresh-1"}
Submit with:
POST /api/order-entry/binary
Content-Type: application/x-senticore-order-entry-batch
Accept: application/x-senticore-mm-batch-response, application/json
X-BSL-Result-Mode: ack
X-Senticore-Response-Mode: detailed
Idempotency-Key: quote-refresh-1
X-Senticore-Order-Entry-Key: <optional provisioned lane key>
The response is an ingress/receipt contract, not a guaranteed terminal fill result:
{
"ok": true,
"seqs": [123],
"derivedOrderIds": ["0x..."],
"acceptedActions": 1,
"responseMode": "detailed",
"ackMode": "ingress_wal"
}
For quote refreshes, reconcile terminal order state from private streams,
drop-copy where provisioned, or account/order reads. Treat HTTP 200 in
ack + detailed mode as "accepted into the venue path", not
"filled/resting/canceled is final".
Response modes
| Header | Beta guidance |
|---|---|
x-bsl-result-mode: ack | Contract name for fast ingress acknowledgement. Confirm availability before production use. |
x-bsl-result-mode: durable | Contract name for durable-boundary acknowledgement. Confirm per account. |
x-bsl-result-mode: full | Target hotpath terminal-result mode. Do not depend on it until your account passes a live conformance run. |
x-senticore-response-mode: detailed | Response body verbosity for accepted action counts, derived order ids, ack metadata, and errors. |
The compatibility alias x-mm-response-mode: detailed is still accepted for
response verbosity, but new BSL clients should send
x-senticore-response-mode.
Private reads and streams
Protected BSL reads require a token or machine credential:
GET /api/v1/bsl/accounts/{account}/executions?cursor=0
Authorization: Bearer <private-session-or-agent-token>
Without a token, the expected response is 401 UNAUTHORIZED. That is not a
market-maker access failure; it means the client has not completed private-read
authentication.
FIX
FIX is not an HTTPS route. In current live operations, FIX is a raw TCP/TLS
listener described by the connectivity bundle, for example fix.sentico-labs.xyz:9878
with TLS SNI fix.sentico-labs.xyz.
FIX Logon uses an HMAC credential issued to a business-line
institutional_agent:
| FIX tag | Value |
|---|---|
553 | API key id |
554 | <apiSecret>:<apiPassphrase> |
Cloudflare HTTPS routing for api.sentico-labs.xyz does not imply raw FIX/TCP
connectivity.
Default private-beta CompID rules:
| FIX field | Value |
|---|---|
49 | Bundle fix.orderEntry.senderCompIdTag49, for example SC-ABCDEF12-123456-OE |
56 | SENTICORE unless the bundle says otherwise |
57 | order_entry or drop_copy |
Changing SenderCompID(49) creates a different persisted session. Keep it
stable across reconnects unless you intentionally reset sequence state.
Local verification
From the repository root, run:
node scripts/e2e/mm-docs-contract-audit.cjs
The script checks BSL metadata, the protected gap-fill 401 behavior, the
institutional-route trap, and a real signed compact order plus cancel cleanup.
It writes tmp/mm-docs-contract-audit-last.json and redacts secrets.
To verify the canonical BSL route after an edge rollout:
MM_DOCS_SUBMIT_ROUTE=/api/v1/bsl/orders/compact \
MM_DOCS_RESULT_MODE=ack \
MM_DOCS_RESPONSE_MODE=detailed \
node scripts/e2e/mm-docs-contract-audit.cjs