Open API spec (v0 draft)
Open API spec (v0 draft)
OpenAPI 3.1, published and versioned. The machine-readable description of every OrangeRails endpoint, request shape,
response shape, and error code.
Status: v0 draft
We're pre-1.0. The schema is generated from the edge function code but not yet committed to additive-only changes.
Breaking changes can happen between v0 and v1. Track the version field at the top of the spec.
At 1.0 (Phase 3 on the roadmap), the schema freezes: additive changes only after that. SDK + client generation become
safe.
Where to find it
- OpenAPI 3.1 YAML — github.com/MorningRevolution/orangerails/blob/dev/docs/openapi.yaml (TBD — will land in Phase 1
once the spec generator is wired in CI)
- Interactive playground — docs.orangerails.com/openapi (planned for Phase 4 when the dedicated dev portal lands)
- Today: the API reference is the human-readable version, kept in sync by hand
What it covers
The spec enumerates every endpoint under /functions/v1/*, both the public catalog and the platform/direct-auth
endpoints:
- or-providers — public catalog of source adapters + categories
- or-platform-display — platform display info for the Connect widget
- or-provision — create or fetch a subaccount for a platform user
- or-connection-create, or-connection-list, or-connection-delete — connection lifecycle
- or-discover-wallets, or-source-wallets-set — wallet selection inside a connection
- or-sync, or-transactions-list — fetch + read normalized transactions
- or-stealth-connection-create, -list, -delete, or-stealth-envelope-fetch, or-stealth-transactions-store — Stealth
Sync sealed envelope endpoints
Each operation declares its request body schema, response schema, error codes, rate limit headers, and auth
requirements.
Schemas worth knowing
ProviderManifest
type: object
required: [slug, displayName, status, multiWallet, credentialFields]
properties:
slug: { type: string }
displayName: { type: string }
description: { type: string }
status: { type: string, enum: [live, beta, coming_soon] }
category: { type: string, enum: [lightning_wallet, on_chain_wallet, payment_processor, exchange, card, mining, bank, lender] }
tags: { type: array, items: { type: string } }
popularity: { type: integer }
multiWallet: { type: boolean }
credentialFields:
type: array
items:
type: object
required: [name, type, label]
properties:
name: { type: string }
type: { type: string, enum: [string, secret] }
label: { type: string }
placeholder: { type: string }
NormalizedTransaction
type: object
required: [id, adapter, direction, type, timestamp]
properties:
id: { type: string, description: "Provider-side stable id (dedup key)" }
external_id: { type: string }
adapter: { type: string }
direction: { type: string, enum: [in, out] }
type: { type: string, enum: [lightning, onchain, trade, deposit, withdrawal, fee] }
amount_sats: { type: integer }
amount: { type: number }
currency: { type: string }
description: { type: string, nullable: true }
counterparty: { type: string, nullable: true }
status: { type: string }
timestamp: { type: string, format: date-time }
external_payload: { type: object, additionalProperties: true }
Error envelope
type: object
required: [error, message]
properties:
error: { type: string, description: "Machine-readable code (e.g. INVALID_PLATFORM_KEY)" }
message: { type: string, description: "Human-readable description" }
Versioning policy (post-1.0)
- MAJOR.MINOR.PATCH in the spec info.version field.
- MAJOR bump = breaking change. Only allowed in a deprecation cycle: announce in newsletter + GitHub release, ship
v(N) alongside v(N+1) for 90 days, then sunset.
- MINOR bump = additive (new endpoint, new optional field, new enum value).
- PATCH bump = doc-only.
A v1 endpoint will be served under /functions/v1/*. When v2 ships, it lives at /functions/v2/* and v1 keeps working for
the deprecation window.
Generators + tooling
These will be officially blessed once the spec lands:
- TypeScript SDK — auto-generated from the spec, published as @orangerails/sdk (planned Phase 1)
- Postman collection — exported from the spec, committed under docs/postman.json
- MCP-compatible tool definitions — derived from the same spec so AI assistants can call the API with full type safety
(Phase 3 — MCP-1.0 spec lock)
What's NOT in the spec
- The Stealth Sync postMessage protocol — that's a browser-to-widget contract, not an HTTP API. Documented separately
in src/stealth/lib/postmessage.ts and on the Stealth Sync wiki page.
- Internal admin endpoints (/admin/*, /portal/*) — not part of the public surface.
- The encryption details (which fields are sealed where) — those live in the Security and threat model doc, because
they're architectural, not API-surface.
See also
- API reference — the human-readable spec
- Quickstart — get a transaction syncing in 10 minutes
- Adapter SDK guide — write your own adapter against the canonical types