Skip to content

docs(scrypt): check in vendor AsyncAPI spec as reference#3737

Open
TaprootFreak wants to merge 2 commits into
developfrom
docs/scrypt-asyncapi-spec
Open

docs(scrypt): check in vendor AsyncAPI spec as reference#3737
TaprootFreak wants to merge 2 commits into
developfrom
docs/scrypt-asyncapi-spec

Conversation

@TaprootFreak
Copy link
Copy Markdown
Collaborator

Why

Scrypt's WebSocket API is documented behind HTTP Basic Auth at doc.client.scrypt.swiss — credentials are in Vaultwarden, not in any developer onboarding doc. Anyone trying to reason about scrypt.service.ts, scrypt-websocket-connection.ts, or scrypt.adapter.ts today has to know the URL exists and get the password before they can see the schema. That has already cost us once: during the 2026-05-21 BTC/EUR fee investigation, the question "does the venue charge a separate fee or embed it in the spread?" could only be answered by fetching the spec live.

Check the rendered AsyncAPI 3.0 YAML into the repo next to the integration code so the source-of-record schema is reachable via grep, survives credential rotation, and lands in clones used by air-gapped reviewers.

What

  • New directory src/integration/exchange/docs/
  • scrypt-asyncapi.yaml — verbatim spec download from https://doc.client.scrypt.swiss/v1/client/customer/documentation/docs/public (130 KB, AsyncAPI 3.0.0, Scrypt WebSocket API v1.0.0)
  • README.md — source URL, fetch date, refresh procedure, and three non-obvious integration-relevant facts pulled from the spec:
    • Fee on Trade and LastFee on ExecutionReport come back as "0" for our Limit orders; the cost lives in the bid/ask spread
    • AvgPx doc string: "Does not include fees"
    • OrdType: RFQ TradedPx is "all-in price that includes fees" — different semantics, future RFQ integration needs its own pricing logic

Non-changes

  • No code changes
  • No secrets or credentials in either file (auth headers documented as schemas only, no key values)
  • Scope is intentionally just Scrypt; if we want to do the same for Kraken/Binance/MEXC, that's a follow-up

Test plan

  • CI green (this PR only touches docs; lint/format/build/tests should be unaffected)
  • Verify the spec parses with an AsyncAPI tool of choice (optional)
  • Spot-check README.md claims against the YAML

The Scrypt integration is built against a non-public WebSocket API that
sits behind HTTP Basic Auth at doc.client.scrypt.swiss. Add the rendered
AsyncAPI 3.0 spec to src/integration/exchange/docs/ so the spec is
discoverable next to the integration code and survives without depending
on continued access to the vendor portal.

The README captures source URL, fetch date, refresh procedure, and the
three non-obvious facts that drive integration choices: Fee="0" defaults,
AvgPx exclusion of fees, and RFQ TradedPx all-in semantics.
Companion to the AsyncAPI WebSocket spec. The FIX API documents
features that are not exposed (or not documented) over WebSocket —
notably:

  - OrdType A = LimitAllIn, where the LIMIT price already includes
    fees. If Scrypt accepts this over WebSocket too, it is the
    cleanest way to bound implicit commission cost.
  - CumFee (Tag 4016) in ExecutionReport — cumulative fee tracked
    server-side.
  - DecisionStatus (Tag 20032) for staged-order lifecycle.
  - CancelOnDisconnect (Tag 20030) auto-cancel semantics.
  - Order State Change Matrices (Filled / Canceled /
    Replace-to-increase / Replace-during-fill).

Also enumerate known FIX-vs-WebSocket divergences in OrdType, ExecType,
and OrdRejReason enums so future contributors don't assume
cross-protocol parity.

PDF source URL kept in the README for re-fetch; the PDF itself is
publicly hosted, no auth needed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant