@stridge/openapi

The public OpenAPI 3.1 specification for the Stridge API, published as an npm package (spec JSON + generated TypeScript types). It is the single source the public API reference site (reference.stridge.com) consumes.

This repo is hand-authored and curated. It is not generated from core — it deliberately re-expresses a small, public subset of the internal API with clean names, public-facing copy, and realistic examples. Core's internal Swagger 2.0 document (../core/docs/swagger.yaml) is the source of truth for field shapes — keep this spec in sync by hand when core's UDA endpoints change.

Scope

Currently the UDA surface only — 7 operations under the UDA tag:

| Method · Path | Operation | Auth | | --- | --- | --- | | GET /uda | list-uda-addresses | X-API-Key | | POST /uda | create-uda-address | X-API-Key | | GET /uda/quote | get-quote | public | | GET /uda/supported-assets | list-supported-assets | public | | GET /uda/{id}/settlements | list-settlements-for-uda | X-API-Key | | GET /uda/settlements/{id} | get-settlement | X-API-Key | | GET /uda/settlements/by-reference | list-settlements-by-reference | X-API-Key |

Onchain Balance is intentionally excluded for now. GET /v1/balance/onchain/{wallet_address} authenticates with X-Gateway-Key (the gateway-scoped key), not X-API-Key. It will be added once its public authentication is reconciled.

Paths are relative to the server base URL, which carries the /v1 prefix (POST /uda → https://api.stridge.com/v1/uda).

Authoring note

The spec is authored as a single file (spec/openapi.yaml) rather than the split-file layout originally sketched in the build plan. At 7 operations this is simpler and avoids cross-file $ref resolution pitfalls; Redocly bundles and dereferences it identically. Split by domain later if the surface grows.

Clean name ↔ core definition map

| Public schema | Core definition | | --- | --- | | UDAAddress | internal_uda_application_http.UDAAddressResponse | | UDAAddressList | …ListUDAAddressResponse | | CreateUDAAddressRequest | …CreateUDAAddressRequest | | DestinationInput / Destination | …DestinationRequest / …DestinationDTO | | DepositAddress / DepositAsset | …DepositAddressDTO / …DepositAssetDTO | | RoutingRuleInput / RoutingRule (+ Match/Destination) | …RoutingRule*Request / …RoutingRule*Response | | Quote / QuoteSide / QuoteFees / QuoteFeeItem / QuoteRoute | …Quote* | | Settlement (+ Deposit/Outbound/Fees/Route) | …Settlement*DTO / …SettlementResponse | | SettlementList / SettlementsByReference | …ListSettlementsResponse / …SettlementsByReferenceResponse | | SupportedAssetsResponse / SupportedAssetChain / AssetInfo / NativeCurrency | …supportedassets.* | | Pagination | …PaginationResponse | | Error | unified from …shared_response.ErrorResponse + echo.HTTPError | | SuccessEnvelope | …shared_response.OkResponse |

Develop

pnpm install
pnpm run lint          # redocly lint
pnpm run build         # → dist/openapi.json, dist/openapi.dereferenced.json, dist/types.d.ts
pnpm exec tsc --noEmit # typecheck the generated types

Consuming

import spec from "@stridge/openapi/dereferenced";   // fully flattened OAS 3.1 doc
import type { paths, components } from "@stridge/openapi/types";

apps/web imports the dereferenced bundle so it never resolves $refs at build time.

Releasing (Changesets)

Releases are automated with Changesets, mirroring stridge-foundation/kit. The Release workflow (.github/workflows/release.yml) runs the shared technance-foundation/github-actions/release@main action on every push to main, using the org-wide NPM_PUBLISH_TOKEN / RELEASE_PUSH_TOKEN secrets — so it works without per-repo secret setup.

The flow:

1. Add a changeset to your PR describing the spec change:

   pnpm changeset

2. When the PR merges to main, the release action opens a "Version Packages" PR that applies the version bump and updates CHANGELOG.md.

3. Merging that PR publishes @stridge/openapi to npm and tags the release.

Nothing publishes until the Version Packages PR is merged, so a pending changeset on main is always safe.

Access: access in .changeset/config.json is public, matching kit. Flip it to restricted if this package should be private (requires the @stridge npm org token to permit restricted publishes).

Local sanity checks (never run pnpm release from a laptop — CI owns it):

pnpm changeset status   # what's pending
pnpm bump               # apply versions locally to preview; revert with git