Skip to main content

Sandbox and Funding

Authentication success does not prove an institutional integration can trade. An unfunded account can pass HMAC, FIX Logon, FIXP negotiate, connectivity, and schema tests while every bid fails at the risk layer.

Current beta model​

There is no public self-serve faucet documented for production beta accounts. Institutional and market-maker testing should use an operator-provisioned, funded beta credential bundle.

The bundle should be delivered as JSON. A copyable template lives at scripts/e2e/institutional-beta-bundle.example.json.

The bundle must include:

FieldRequired
environment, apiBaseUrlTarget beta environment and API base URL.
ownerWallet20-byte owner wallet.
accountIdHex32-byte trading-account id for control-plane operations.
engineAccount20-byte engine account for balances, signed actions, FIX/FIXP, and streams.
agent.id, agent.type, agent.scopesinstitutional_agent with at least read, trade, cancel, quote, drop_copy.
hmac.apiKeyId, hmac.apiSecret, hmac.apiPassphraseHMAC credential for machine auth and FIX/FIXP.
orderEntry.submitPath, orderEntry.signedBatchFile, orderEntry.idempotencyKeyKnown-good signed batch and submit route for conformance.
expectedFunding.freeUsdcMicroAtLeastMinimum free USDC the first known-good quote requires.
knownGoodQuoteMarket, book, side, price, qty, and time-in-force for a tiny post-only quote.

Minimal shape:

{
  "environment": "beta",
  "apiBaseUrl": "https://api.sentico-labs.xyz",
  "ownerWallet": "0x1111111111111111111111111111111111111111",
  "accountIdHex": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "engineAccount": "0x2222222222222222222222222222222222222222",
  "agent": {
    "id": "agt_...",
    "type": "institutional_agent",
    "scopes": ["read", "trade", "cancel", "quote", "drop_copy"]
  },
  "hmac": {
    "apiKeyId": "spk_...",
    "apiSecret": "sps_...",
    "apiPassphrase": "spp_..."
  },
  "orderEntry": {
    "submitPath": "/api/order-entry/binary",
    "contentType": "application/x-senticore-order-entry-batch",
    "signedBatchFile": "tmp/known-good-bsl-batch.json",
    "idempotencyKey": "quote-7-yes-bid-0"
  },
  "expectedFunding": {
    "asset": "USDC",
    "freeUsdcMicroAtLeast": "100000000"
  },
  "knownGoodQuote": {
    "kind": "QuoteReplace",
    "market": 7,
    "book": "YES",
    "side": "Bid",
    "price": 100000,
    "qty": 100000,
    "timeInForce": "post_only",
    "requiredUsdcMicro": "10000"
  }
}

Funding preflight​

Before any quote submit:

GET /api/v1/accounts/:engineAccount/bootstrap?fresh=true
Authorization: Bearer <read token>

Required response properties:

{
  "account": "0x2222222222222222222222222222222222222222",
  "balanceSource": "matching_engine",
  "syncStatus": "synced",
  "balances": {
    "freeUsdcMicro": "100000000",
    "lockedUsdcMicro": "0",
    "inOrdersUsdcMicro": "0"
  },
  "risk": {
    "freeUsdcMicro": "100000000"
  }
}

Use balances.freeUsdcMicro as the operational free-USDC check. If the value is below the required notional for the first quote, stop and request funding.

You can run the same check through the external conformance harness:

node scripts/e2e/institutional-conformance-kit.cjs \
  --bundle-file tmp/institutional-beta-bundle.json

The harness validates the manifest, applies missing env vars from it, then fails the funding gate when fresh bootstrap free USDC is missing or below expectedFunding.freeUsdcMicroAtLeast.

Required notional​

For a bid:

requiredUsdcMicro = floor(priceMicro * qtyMicro / 1_000_000)

Example:

priceMicro = 100000
qtyMicro   = 100000
required   = 10000 micro USDC

The funded bundle should exceed this by a wide margin because open-order holds, fees, and account-level risk can raise the effective requirement.

What to send support​

When a funded account still rejects with risk:

{
  "engineAccount": "0x...",
  "accountIdHex": "0x...",
  "market": 7,
  "book": "YES",
  "side": "Bid",
  "price": 100000,
  "qty": 100000,
  "requiredUsdcMicro": "10000",
  "bootstrap": {
    "balanceSource": "matching_engine",
    "syncStatus": "synced",
    "balances": {
      "freeUsdcMicro": "0",
      "lockedUsdcMicro": "0",
      "inOrdersUsdcMicro": "0"
    },
    "risk": {
      "freeUsdcMicro": "0"
    }
  },
  "submitResponse": {
    "ok": false,
    "code": "insufficient_balance",
    "error": "..."
  }
}

If the bootstrap shows no funding, the fix is provisioning, not client code.

Last updated on