> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trdrs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect SDK

> Open the hosted TRDRS account picker from your website without putting a Venue key in the browser.

The Connect SDK adds the account picker to your website. Your backend creates a short-lived session,
then the SDK opens the hosted picker in a secured iframe. You do not build or copy an iframe yourself.

<Info>
  Hosted Connect is a preview. The sandbox host is
  `https://trdrsco-connect-sandbox.fly.dev`. Production access and the final public host require
  approval before launch.
</Info>

## Before you start

1. Create a Venue key with `connect:manage` in your sandbox back office.
2. Add the exact website origin under **Developers → Connect websites**. Paths and wildcards are not accepted.
3. Keep the Venue key on your server. Only the short-lived Connect token goes to the browser.

## 1. Create a session on your server

This route must run on your backend. Replace the venue id and email with the trader opening Connect.

```js server.js theme={null}
const response = await fetch(
  `https://sandbox.trdrs.co/api/partner/venues/${process.env.TRDRS_VENUE_ID}/connect/sessions`,
  {
    method: 'POST',
    headers: {
      authorization: `Bearer ${process.env.TRDRS_VENUE_KEY}`,
      'content-type': 'application/json',
      'idempotency-key': crypto.randomUUID(),
    },
    body: JSON.stringify({
      origin: 'https://your-app.example',
      email: 'trader@example.com',
      expiresInSeconds: 300,
    }),
  },
)

if (!response.ok) throw new Error('Connect session could not be created')
const { session } = await response.json()

// Return session.token to this trader's browser. Never return the Venue key.
```

The token lasts for at most ten minutes, belongs to one venue, one environment, one approved origin,
and one intended email.

## 2. Open Connect in the browser

Import the browser module, request a token from your backend, and call `open()`. The SDK creates and
removes the iframe for you.

```html index.html theme={null}
<button id="connect-account" type="button">Connect a trading account</button>
<p id="connect-status" role="status"></p>

<script type="module">
  import { createConnect } from
    'https://trdrsco-connect-sandbox.fly.dev/sdk/connect.js'

  const button = document.querySelector('#connect-account')
  const status = document.querySelector('#connect-status')

  button.addEventListener('click', async () => {
    const response = await fetch('/api/connect-session', { method: 'POST' })
    if (!response.ok) throw new Error('Connect session could not be created')
    const { token } = await response.json()

    const connect = createConnect({
      token,
      host: 'https://trdrsco-connect-sandbox.fly.dev',
    })

    connect.on(event => {
      if (event.type === 'connected') status.textContent = `Connected: ${event.accountId}`
      if (event.type === 'closed') status.textContent = 'Connect was closed.'
      if (event.type === 'error') status.textContent = `Connect error: ${event.code}`
    })

    connect.open()
  })
</script>
```

## Events

| Event       | Meaning                                                                      |
| ----------- | ---------------------------------------------------------------------------- |
| `ready`     | The hosted picker loaded and is ready for the trader.                        |
| `connected` | An account connected successfully. The event includes its TRDRS `accountId`. |
| `closed`    | The trader closed Connect without completing another connection.             |
| `error`     | Connect could not continue. The event includes a safe error `code`.          |

Calling `close()` removes the iframe. Calling `open()` again needs a new session token after the old
session completes or expires.

## Redirect instead of an iframe

Use `connect.redirect()` when an embedded dialog does not fit your application, such as a small
mobile web view. Connect returns to the current page after the hosted flow.

## Read the result from your backend

The browser event is for interface feedback. Your backend can read the authoritative session result:

```bash theme={null}
curl "https://sandbox.trdrs.co/api/partner/venues/$TRDRS_VENUE_ID/connect/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TRDRS_VENUE_KEY"
```

The response is redacted. It never returns provider credentials, browser handoff tokens, or another
trader's account.

## Security rules

* Never put a Venue key in JavaScript, HTML, a mobile bundle, or a Connect URL.
* Register exact origins. `https://app.example.com` and `https://admin.example.com` are different origins.
* Create the session for the signed-in trader's real email. A different TRDRS user cannot claim it.
* Treat `connected` as interface feedback and confirm important work from your backend.
* Use a fresh idempotency key when you intentionally create a new session.

## Related pages

* [Connect overview](/guides/connect-overview)
* [Venue keys](/guides/venue-keys)
* [Create a Connect session](/api-reference/venue-platform-preview/create-a-connect-link-session)
* [API idempotency](/partner-platform/overview/idempotency)