Market Maker Start Here

Use this page first when integrating a market-maker bot, quote engine, or institutional OMS. It gives the intended beta path end to end: which lane to use, which agent to create, which order types are supported, and how to smoke test the connection.

Institutional integration spec

Before implementing, read Institutional Operational Spec , Institutional Hotpath Latency and then run Place Your First Institutional BSL Quote. Those pages define the account model, auth matrix, nonce/replay behavior, funding preflight, risk-debug fields, hotpath ACK boundaries, and conformance gates.

Do not start with /api/v1/institutional/*

Those routes are provisioning, reporting, and account-management surfaces. They are not the self-serve market-maker order-entry path. For trading, start with REST/WebSocket, FIX 4.4, BSL Direct TCP, or FIXP as listed below.

1. Pick the lane

Need	Lane	Endpoint	Use it for
Simple bots and dashboards	REST + WebSocket	https://api.sentico-labs.xyz / wss://api.sentico-labs.xyz	Signed JSON actions, account reads, market data, frontend-like workflows
Existing FIX stack	FIX 4.4	fix.sentico-labs.xyz:9878 with SNI fix.sentico-labs.xyz	Session-auth order entry, cancels, cancel-replace, status, mass-cancel, drop-copy
Lowest Senticore-native wire	BSL Direct TCP	bsl.sentico-labs.xyz:9001 with SNI bsl.sentico-labs.xyz	Persistent raw TCP/TLS quote flow, 192-byte compact action frames, per-action account signature
SBE/FIXP shops	Binary-FIX / FIXP	fixp.sentico-labs.xyz:9879 with SNI fixp.sentico-labs.xyz	SOFH + SBE + FIXP recoverable sessions, binary New/Cancel/CancelReplace/MassCancel

FIX, BSL Direct TCP, and FIXP are raw TLS-over-TCP lanes. Keep their DNS records DNS-only. They do not work through a Cloudflare HTTPS proxy.

2. Create the right agent

For FIX, BSL, and FIXP, create an institutional_agent with an HMAC credential. A normal api_agent is useful for standard HTTP bots and private reads, but it is rejected for institutional order entry.

Minimum beta scopes for a market-maker agent:

["read", "trade", "cancel", "quote", "drop_copy"]

Create the agent and first HMAC credential in one call:

POST /api/agents/create
Content-Type: application/json

{
  "authorization": {
    "domain": "app.sentico-labs.xyz",
    "appName": "SentiPredict",
    "scheme": "senticore_typed_v2",
    "environment": "Arbitrum One",
    "chainId": 42161,
    "userWalletAddress": "0xOwnerWallet",
    "agentPublicKey": "0xGeneratedAgentAddress",
    "label": "MM quote engine",
    "agentType": "institutional_agent",
    "scopes": ["read", "trade", "cancel", "quote", "drop_copy"],
    "policy": {},
    "expiresAt": 1790000000000,
    "authorizationNonce": "7c4a0e4a5d43c4d8c9e2a55b",
    "issuedAt": 1760000000000,
    "signature": "0x..."
  },
  "issueInitialCredential": true
}

The wallet owner signs the authorization message. Store these returned values immediately because the raw secret material is shown only once:

Returned value	Used by
apiKeyId	HTTP HMAC header, FIX Username(553), FIXP credentials
apiSecret	HTTP HMAC signing, FIX Password(554), FIXP credentials
apiPassphrase	HTTP HMAC passphrase, FIX Password(554), FIXP credentials
Agent private key	Delegated signing, if your bot signs account actions directly

Full typed-signing details are in API Agents.

3. Read the connectivity bundle

After creating the institutional_agent, read the bundle. Use the returned hosts, ports, SNI values, and FIX CompIDs instead of guessing.

GET /api/v1/bsl/connectivity
SC-Auth-Version: 2
SC-Key: <apiKeyId>
SC-Nonce: <monotonic nonce>
SC-Timestamp: <unix ms>
SC-Passphrase: <apiPassphrase>
SC-Signature: <hmac signature>

Alias:

GET /api/v1/fix/connectivity

The bundle returns:

Field	Meaning
bslTcp.host, bslTcp.port, bslTcp.tlsSni	Native BSL Direct TCP endpoint
fix.host, fix.port, fix.tlsSni	Native FIX 4.4 endpoint
fix.orderEntry.senderCompIdTag49	FIX order-entry SenderCompID(49)
fix.dropCopy.senderCompIdTag49	FIX drop-copy SenderCompID(49) when available
fix.targetCompIdTag56	FIX TargetCompID(56), normally SENTICORE

4. Know which order interface does what

Interface	Place order	Cancel	Replace / quote refresh	Status / drop-copy
REST signed JSON	Limit/market signed actions	Signed cancel actions	Signed cancel + new action or route-specific batch helper	Account/order reads, private WS/SSE
BSL compact HTTP	PlaceOrder inside compact batch	Signed cancel action inside compact batch	Compact batch quote refresh/cancel-replace where enabled	Private streams/gap-fill; response is an ack unless full is enabled
BSL Direct TCP	192-byte compact action frame	Compact signed cancel frame with routingMarket	Persistent quote-loop frames, same action semantics as compact submit	Sequenced acks plus private streams/drop-copy
FIX 4.4	D NewOrderSingle	F OrderCancelRequest	G OrderCancelReplaceRequest, q MassCancel	H OrderStatusRequest, AF MassStatus, drop-copy session
FIXP/SBE	Template 1 NewOrderSingle	Template 2 OrderCancelRequest	Template 3 CancelReplace, template 4 MassCancel	Template 5 OrderStatusRequest, template 10 ExecutionReport, template 12 BusinessMessageReject

FIX 4.4 supports both prediction and spot markets. Prediction/binary placement requires Book(9100) (YES or NO); spot placement omits Book(9100) and is translated server-side to SpotPlaceOrder / SpotQuoteReplace.

FIXP/SBE uses Recoverable-flow sessions. On reconnect, reuse the same sessionId, authenticate the same account during Negotiate, then request any missed server messages with RetransmitRequest. The gateway will not resume a retained sessionId for a different account.

5. Treat acknowledgements correctly

Fast acknowledgements are admission signals, not fill truth.

Response	Meaning
HTTP/BSL resultMode: ack	Requested a fast admission response.
HTTP/BSL ackMode: ingress_wal / ackClass: ingress_wal	The configured low-latency boundary was reached. Reconcile final state separately.
FIX ExecutionReport(35=8, 150=A, 39=A)	PendingNew admission ack. Working/fill/cancel state arrives later.
FIXP execution ack	Session-level order response. Continue consuming execution/drop-copy frames.

For final strategy state, reconcile from private streams, FIX/FIXP drop-copy, account/order reads, or protected BSL gap-fill. For portfolio/bootstrap reads after fast cycles, request a fresh read where supported instead of relying on a cached projection.

For quote-loop latency, measure bsl.timing.durationsUs.coreAck or x-mm-perf-total-us. Do not compare a full, applied, or durable response to the sub-50 ms market-maker hotpath target.

6. Keep nonce families separate

Value	Owner	Rule
SC-Nonce	HMAC credential / API key	Monotonic per key; reuse is an auth replay.
Action payload.nonce	20-byte engine account	Must be unused and inside the account nonce window; re-sign on nonce rejects.
Idempotency-Key	Client request	Same key plus same body can replay the response; it does not change the signed action.

Changing only Idempotency-Key cannot fix nonce_below_floor, nonce_replayed, or nonce_outside_window. Re-read bootstrap, pick a fresh in-window action nonce, rebuild the payload, and re-sign.

7. Smoke-test before trading size

Run the external conformance harness from the repository root:

node scripts/e2e/institutional-conformance-kit.cjs --offline

Then run live credential and funding preflight:

: "${SENTICORE_API_BASE_URL:=https://api.sentico-labs.xyz}"
: "${SENTICORE_API_KEY_ID:?set SENTICORE_API_KEY_ID from your beta bundle}"
: "${SENTICORE_API_SECRET:?set SENTICORE_API_SECRET from your beta bundle}"
: "${SENTICORE_API_PASSPHRASE:?set SENTICORE_API_PASSPHRASE from your beta bundle}"
: "${SENTICORE_ENGINE_ACCOUNT:?set SENTICORE_ENGINE_ACCOUNT to your 20-byte engine account}"
export SENTICORE_MIN_FREE_USDC_MICRO=100000000
node scripts/e2e/institutional-conformance-kit.cjs

FIX 4.4 order-entry smoke:

python scripts/fix_conformance_smoke.py \
  --host fix.sentico-labs.xyz \
  --port 9878 \
  --tls-server-name fix.sentico-labs.xyz \
  --sender-comp-id "$FIX_SENDER_COMP_ID" \
  --target-comp-id SENTICORE \
  --account "$ACCOUNT" \
  --username "$API_KEY_ID" \
  --password "${API_SECRET}:${API_PASSPHRASE}" \
  --market-id 1 \
  --price 100000 \
  --replace-price 110000 \
  --qty 10000 \
  --rounds 2

FIXP codec and live-session smoke:

python scripts/fixp_conformance_smoke.py verify-golden

python scripts/fixp_conformance_smoke.py session \
  --host fixp.sentico-labs.xyz \
  --port 9879 \
  --tls \
  --sni fixp.sentico-labs.xyz \
  --api-key "$API_KEY_ID" \
  --api-secret "$API_SECRET" \
  --api-passphrase "$API_PASSPHRASE" \
  --account "$ACCOUNT" \
  --market 1 \
  --side bid \
  --price 100000 \
  --qty 10000 \
  --orders 20 \
  --cancel-after-ack

Common integration mistakes

• Creating an api_agent and trying to use it for FIX, BSL, or FIXP order entry. Use institutional_agent.
• Sending FIX TLS SNI as api.sentico-labs.xyz. Use fix.sentico-labs.xyz.
• Putting a 20-byte wallet address into accountIdHex. Internal accountIdHex values are 32 bytes; omit the field unless you know the exact trading-account id.
• Treating a fast ack as a fill or resting-order confirmation.
• Reusing a different FIX SenderCompID(49) on every reconnect. Keep it stable unless you intentionally reset sequence state.
• Orange-proxying fix., bsl., or fixp. through Cloudflare. These lanes are raw TCP/TLS, not HTTP.

Next pages

• Connectivity & Endpoints
• Institutional Operational Spec
• Institutional Hotpath Latency
• Place Your First Institutional BSL Quote
• Institutional Conformance Kit
• API Agents
• FIX/BSL Connectivity Bundle
• BSL Order Entry
• FIX Order Entry
• Binary-FIX / FIXP Conformance