ISV program
An ISV (independent software vendor) builds an app that acts on behalf of other STX members, using OAuth. Your users keep their own STX accounts and connect them to your app. They sign in on STX, approve the access you ask for, and can disconnect at any time. You never see their password, their keys or their funds, and nothing your app holds can move money.
How the protocol works, from the authorization code flow to scopes, tokens and errors, is covered in the OAuth section. These pages cover what the program gives you and how to get access.
What you get
Section titled “What you get”- Scoped access. Named slices of a member’s account, such as
profile.read,balance.read,orders.readandorders.write. You ask for the fewest you need, and every token is confined to them. No scope moves money. See Scopes. - Consent hosted by STX. Sign-in, sign-up, two-factor and the consent screen all run on STX. Members see your app’s name and logo, and can revoke it from Connected apps in their account. See Hosted pages.
- Member and app tokens. A member token to act for one member, a refresh token to keep that access alive, and an app token to read the market and event catalogue as your app. See Tokens and security.
- The same API. An access token is a bearer on the same REST API and WebSocket channels a signed request uses, limited to the scopes the member approved.
- Attribution. Every order your app places for a member is recorded as placed by your app.
- A TypeScript SDK.
@stxapp/stx-typescriptruns the whole flow for you, from linking a member to refreshing and revoking their tokens. See With the TypeScript SDK.
Access
Section titled “Access”Access is by invite. STX registers your app and gives you its client credentials, the host to test against, and a member account funded with play money to connect it to.
Get demo access
Section titled “Get demo access”To ask for an invite, contact developer support with your app’s name and what it does. To set up your app, STX needs:
- an application name and logo, shown to members on the consent screen and in Connected apps;
- its application type, from the table below;
- one or more callback URLs (redirect URIs), where STX returns the member after consent. They are matched exactly, byte for byte, at both the authorize and token steps, except a local callback (
localhost,127.0.0.1,[::1]), which matches on any port. The allowed forms depend on your application type. None for a Server-to-server app. No fragment; - the scopes your app may ever request: member scopes, app scopes, or both. Every request is narrowed against this list;
- the IP addresses your app calls STX from, as CIDR blocks (
203.0.113.0/24,2001:db8::/32; no wider than /8 for IPv4 or /32 for IPv6). Required if your app has any write scope (orders.write,terms.write), optional otherwise. When set, token requests, REST calls and WebSocket connections from any other address are refused with403 ip_not_allowed. Developing locally? Add your own public IP.
You receive a client_id and, for a Web app or Server-to-server app, a one-time client_secret. The secret is shown once and cannot be recovered; store it on your server. Rotating it invalidates the old one immediately.
Application types
Section titled “Application types”| Type | For | Client secret | Callbacks in production |
|---|---|---|---|
| Web app | an app with its own server | yes | https only |
| Browser app | a single-page app with no server | no, PKCE only | https only |
| Mobile or desktop app | an installed app | no, PKCE only | https link, reverse-domain custom scheme (com.example.app:/callback), or http://localhost / 127.0.0.1 / [::1] on any port |
| Server-to-server | your backend, no member sign-in (client_credentials) |
yes | none |
The type is fixed at registration. Outside production, every type with callbacks may also register localhost, 127.0.0.1 and [::1] callbacks (http or https) that match on any port, so you can develop locally.
What it takes to integrate
Section titled “What it takes to integrate”- Get a demo client through your invite (see Get demo access).
- Run the authorization code flow to turn a member’s consent into tokens. See Authorization code flow.
- Call STX for the member with the access token as a bearer on
/api/v1and the WebSocket, limited to the effective scope. - Keep access alive by refreshing, and drop it cleanly when the member disconnects. See Tokens and security.
Sample app
Section titled “Sample app”Sideline is a fictional app built on STX OAuth, published as a public example. It links a member’s account from its backend, reads their balance, positions and orders, places and cancels orders for them, streams their account data, reads public market data on its own app token, and unlinks on request. It is built on the TypeScript SDK and runs against the demo exchange with the client you are given.
Try it live at sideline.sportsxapp.com. It runs against the US demo exchange: to link an account, sign up on demo.stxapp.io first. No real money is involved.