@stridge/openapi

@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