# Platform Integration

Source: https://docs.tradeit.app/sdk

Connect your users’ brokerages to your app. Read accounts, holdings, and trade history, then let users review and approve trades from your product.

Embed the Trade It Portal with two modes: **Onboarding** for a user’s first visit, then **Connection** whenever they need to add or reconnect a brokerage. Users own their brokerage connections and delegate access to your app.

## Build with the AI Skill [#build-with-the-ai-skill]

Install the **Trade It Developer** plugin in your coding assistant. It bundles [`trade-it-developer`](https://github.com/trade-it-inc/skills) and its reference guides. Start a new session after installing.

```text
/plugin marketplace add trade-it-inc/skills
/plugin install trade-it-developer@trade-it
```

```bash
codex plugin marketplace add trade-it-inc/skills
codex plugin add trade-it-developer@trade-it
```

1. Open **Settings → Plugins**.
2. Paste `https://github.com/trade-it-inc/skills` into the plugin search box.
3. Open **Trade It Developer** and select **Install**.

1. Enable **`chat.plugins.enabled`** in VS Code settings.
2. Run **Chat: Install Plugin From Source** in the Command Palette.
3. Enter `https://github.com/trade-it-inc/skills` and install **Trade It Developer**.

Install only the skill with the [skills CLI](https://github.com/vercel-labs/skills). Add `--agent opencode` (or another assistant) to choose where it installs:

```bash
npx skills add trade-it-inc/skills --skill trade-it-developer
```

To install by hand, copy the **entire** `skills/trade-it-developer/` folder, including `references/`, into your assistant's skills directory.

Then give your AI coding client this prompt:

```text
Use the Trade It skill (trade-it-developer) to integrate Trade It into this platform.
Read https://docs.tradeit.app/sdk and its linked guides first.

Use our existing framework, authentication, and database.

Use POST /api/portal with Basic client credentials for the first visit:
put redirect_uri, state, PKCE, and optional email_hint in oauth_options.
This opens the Trade It Portal in Onboarding mode: an access overview, sign-in,
and brokerage connection in one modal. Supply email_hint to start OTP,
or omit it to offer social and email sign-in.
Set up server-side PKCE/state validation, the onAuthorization code
exchange, and per-user token storage and refresh.
For subsequent connections, call the same endpoint with the user’s saved
Bearer access token and omit oauth_options. Refresh expired tokens first.
Use connect_options to customize the portal in either mode.
Keep the client secret and OAuth tokens on the server.

Add an account selector and holdings for the selected account.
Add trade history using the REST API.
Use @trade-it/react for the trade review modal.
If relevant, set up user review and approval of trades before executing.

Tell me which callback URL to register and which environment variables to
set. I will supply credentials through the environment, not this chat.
Verify OTP, code exchange, refresh, and reconnect paths.
```

## 1. Create your organization and get credentials [#_1-create-your-organization-and-get-credentials]

1. Sign in to [Trade It](https://tradeit.app) and open [Organizations](https://tradeit.app/partner). Create your organization with a name, logo URL, and website.
2. Register a redirect URI for each environment. For Onboarding mode, its origin must match the website opening it.
3. Complete checkout and save your **Client ID** and **Client Secret** on your server. The secret is shown only once.

![Partner portal settings screen](https://images.tradeit.app/docs/partner_portal_settings.png)

Organization details are editable at any time from the partner portal

## 2. Integrate the Trade It Portal [#_2-integrate-the-trade-it-portal]

The Trade It portal is a drop-in modal that explains your app’s access, signs the user in, and connects their first brokerage. Start by hosting the portal in [Onboarding mode](/sdk/onboarding).

![The Trade It Portal’s first step, showing your app’s access, security, and privacy information.](https://images.tradeit.app/docs/onboarding_info_half.png)

> **Tokens**
>
> The portal emits an access and refresh token for each user. Save these and use them to interact with the user's brokerage data.

> **Prefer a custom sign-in experience?**
>
> The [OAuth guide](/sdk/authentication) explains how to use redirects and handle authorization in your own onboarding flow.

## 3. Build the experience [#_3-build-the-experience]

That's it! Once users are connected, you're ready to interact with their accounts!

Use these guides to understand each capability:

| Guide | What you will build |
| --- | --- |
| [Read accounts](/sdk/accounts) | Show the user’s accounts and let them choose one. |
| [Read holdings](/sdk/holdings) | Display positions for the selected account. |
| [Read trade history](/sdk/trade-history) | Fetch the user’s recent trades. |
| [Place trades](/sdk/trades) | Use the React trade modal or submit user-approved orders through your server. |
| [Webhooks](/sdk/webhooks) | Receive account, connection, and trade updates. |

Refer to [API](/api) for sample requests/responses.

## 4. Manage subsequent connections [#_4-manage-subsequent-connections]

When a user wants to add or reconnect a brokerage, use the portal in [Connection mode](/sdk/connect).

The user goes straight to brokerage connection, without signing in or approving access again.

![The Trade It Portal’s first step, showing your app’s access, security, and privacy information.](https://images.tradeit.app/docs/portal_connection_mode_half.png)

| Mode | Authorization header | Experience |
| --- | --- | --- |
| Onboarding · First visit | `Basic` client credentials | Sign in, authorize, connect |
| Connection · Later visits | `Bearer` user access token | Connect directly |

For integration help, [contact us](https://tradeit.app/contact).
