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.

Use the tested beta path first

Do not start with /api/v1/institutional/*. Those routes are account/reporting and provisioning surfaces, not the market-maker order-entry path.

For live beta quoting, start with signed BSL order-entry through POST /api/order-entry/binary or the direct trading-plane compatibility route POST /api/v1/mm/orders/batch.bin. The canonical BSL route is POST /api/v1/bsl/orders/compact; use it only after operations confirms the deployed edge has the BSL submit allowlist for your environment.

What is verified in 0.1.3 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.
Signed compact order submit	Live on compatibility path	Use POST /api/order-entry/binary or /api/v1/mm/orders/batch.bin with x-senticore-response-mode: detailed.
FIX order entry	Provisioned	Raw TCP/TLS, direct host/port from onboarding, mm_agent 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.
mm_agent HMAC credential	FIX Logon, 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. Keep owner wallet keys out of trading systems.

Order-entry 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-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 detailed mode as "accepted into the venue path", not "filled/resting/canceled is final".

Response modes

Mode/header	Beta guidance
x-senticore-response-mode: detailed	Tested private-beta order-entry mode. Use this first.
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.

Private reads and streams

Protected BSL reads require a token or machine credential:

GET /api/v1/bsl/accounts/{account}/executions?fromSeq=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 exposed directly by onboarding, for example 46.225.50.61:9878 with TLS SNI api.sentico-labs.xyz.

FIX Logon uses an HMAC credential issued to a business-line mm_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.

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=detailed \
node scripts/e2e/mm-docs-contract-audit.cjs