Start Integration with Your AI Agent

Quickly integrate Wealthica Connect by copying a ready-made prompt into your AI coding agent. Each prompt contains the full specification — your agent will scaffold the backend and frontend in one go.

Compatible with: Claude Code, ChatGPT, Cursor, Windsurf, GitHub Copilot, Gemini Code Assist, or any AI coding assistant.

For a complete overview of the Wealthica API, see the Introduction.

---

There are two ways to integrate Wealthica Connect into your application. Choose the one that fits your architecture:

• Popup Widget Flow — Best for web apps. Opens a popup widget inside your page using the JS SDK. The user connects their account without leaving your app, and you receive the result via JS callbacks.
• OAuth/Redirect Flow — Best for mobile apps, desktop apps, or when you need full control over the UX. Redirects the user to the Wealthica Connect URL, and redirects them back to your app with the result.

Quick Start: Popup Widget Flow

caution

Do not paste your Client Secret into the prompt. The prompts below reference it via an environment variable (WEALTHICA_CLIENT_SECRET). Store the secret in your .env file or secrets manager — your AI agent will read it from there when generating backend code.

Copy the prompt below, replace the [REPLACE: ...] placeholders, and paste it into your AI coding agent:

# Task

Integrate Wealthica Connect into my app using the **Popup Widget flow** (iframe-based). Build all files needed to:
1. Authenticate with the Wealthica API from my backend
2. Open the Wealthica Connect Widget in the frontend
3. Handle the connection result and fetch institution data

Read the specification below carefully before writing any code. Do not skip any step.

---

# My app context

- **Stack**: [REPLACE: e.g. "Next.js frontend + Express backend" or "React SPA + Django API"]
- **Wealthica Client ID**: [REPLACE: your Client ID]
- **Wealthica Client Secret**: stored in environment variable `WEALTHICA_CLIENT_SECRET` (do NOT paste the actual secret here)
- **How I identify logged-in users**: [REPLACE: e.g. "JWT with userId in payload" or "session.user.id"]

---

# Specification

## Step 1 — Backend auth endpoint

Create a `POST /wealthica/auth` endpoint on my backend server.

This endpoint is called by the Wealthica JS SDK from the browser. It must:
1. Identify the currently logged-in user (using my app's own auth — see "My app context" above).
2. Request a Wealthica user token by calling:

```
POST https://api.wealthica.com/auth/token
Headers:
  loginName: <my_user_identifier>
  Content-Type: application/json
Body:
  { "clientId": "<CLIENT_ID>", "secret": process.env.WEALTHICA_CLIENT_SECRET }
```

3. Return the response as-is: `{ "token": "..." }`

**Security rule**: The Client Secret must only exist on the backend. Never send it to the browser.

## Step 2 — Frontend: install SDK and open the Connect Widget

Install the SDK:
```bash
npm install wealthica-sdk-js
```

Or load via CDN:
```html
<script src="https://unpkg.com/wealthica-sdk-js@0.0.14/dist/wealthica.js"></script>
```

Then initialize and wire up a "Connect Account" button:

```js
import Wealthica from 'wealthica-sdk-js';

// Initialize — the SDK will call /wealthica/auth automatically to get a token
const wealthica = Wealthica.init({
  clientId: '<CLIENT_ID>',
  authEndpoint: '/wealthica/auth',
});
const user = wealthica.login();

// Open the Connect Widget when the user clicks "Connect Account"
function openConnect() {
  user.connect()
    .onConnection((institutionId, data) => {
      // SUCCESS — the user connected an account.
      // `institutionId` is the Wealthica institution ID. Store it in your database.
      // `data.provider` is the provider type string (e.g. "questrade", "td").
    })
    .onError((error) => {
      // FAILURE — the user closed the widget, or there was a connection error.
      // `error` has: error_type (number), message (string),
      //              institution (string|undefined), provider (string|undefined)
    })
    .onEvent((name, data) => {
      // OPTIONAL — lifecycle events during the process:
      //   SCREEN_LOADED, PROVIDER_SELECTED, SUBMIT_CREDENTIALS,
      //   SUBMIT_ANSWER, ERROR, CLOSE, FORCE_CLOSE, etc.
    });
}
```

## Step 3 — Backend: fetch institution data

After the frontend sends the `institutionId` to the backend, fetch the full institution object:

```
GET https://api.wealthica.com/institutions/<institutionId>
Headers:
  Authorization: Bearer <user_token>
```

Store the `institutionId` in your database. Wealthica automatically syncs institution data daily — you can retrieve updated data at any time with the same GET request.

## Step 4 — Reconnect and Verify MFA (implement later, but wire the handlers now)

For reconnecting a disconnected account (expired credentials):
```js
user.reconnect(institutionId).onConnection(...).onError(...);
```

For answering a security question / MFA verification (without re-entering credentials):
```js
user.verifyMfa(institutionId).onConnection(...).onError(...);
```

---

# Constraints

- Token lifetime: 1 hour for API calls. The Connect Widget session expires 10 minutes after token creation — always request a fresh token right before opening the widget.
- The widget renders inside `<iframe name="wealthica-connect-widget">`. If this element already exists on the page, the SDK uses it. Otherwise, the SDK creates one as a fullscreen overlay.
- For testing, use the `demo` provider: username `wealthica`, password `wealthica` for a successful connection.

# References (fetch these docs for the latest API details)

- JS SDK source & examples: https://github.com/wealthica/wealthica-sdk-js
- Connect a user (full reference): https://wealthica.com/docs/connecting-a-user
- API reference: https://wealthica.com/docs/api

Quick Start: OAuth/Redirect Flow

Copy the prompt below, replace the [REPLACE: ...] placeholders, and paste it into your AI coding agent:

# Task

Integrate Wealthica Connect into my app using the **OAuth/Redirect flow**. Build all files needed to:
1. Generate a Wealthica user token on the backend
2. Redirect the user to the Wealthica Connect URL
3. Handle the redirect callback with the connection result

Read the specification below carefully before writing any code. Do not skip any step.

---

# My app context

- **Stack**: [REPLACE: e.g. "Express.js backend serving a React SPA" or "Rails API + React Native mobile"]
- **Wealthica Client ID**: [REPLACE: your Client ID]
- **Wealthica Client Secret**: stored in environment variable `WEALTHICA_CLIENT_SECRET` (do NOT paste the actual secret here)
- **Redirect URI**: [REPLACE: e.g. "https://myapp.com/wealthica/callback" — must be registered with Wealthica]
- **How I identify logged-in users**: [REPLACE: e.g. "JWT with userId in payload" or "session.user.id"]
- **Platform**: [REPLACE: "web", "iOS", "Android", or "desktop"]

---

# Specification

## Step 1 — Backend: generate a Wealthica user token

Create a backend function that generates a Wealthica user token for a given user:

```
POST https://api.wealthica.com/auth/token
Headers:
  loginName: <my_user_identifier>
  Content-Type: application/json
Body:
  { "clientId": "<CLIENT_ID>", "secret": process.env.WEALTHICA_CLIENT_SECRET }
Response:
  { "token": "eyJ..." }
```

**Security rule**: The Client Secret must only exist on the backend. Never send it to the browser or mobile app.

## Step 2 — Redirect the user to Wealthica Connect

The Connect URL must be loaded as a **POST request** with the token in form data. The simplest approach is to render a server-side page with an auto-submitting HTML form:

```html
<form method="POST" action="https://connect.wealthica.com/connect?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&state=<STATE>">
  <input type="hidden" name="token" value="<USER_TOKEN>" />
  <noscript><button type="submit">Continue to Wealthica</button></noscript>
</form>
<script>document.forms[0].submit();</script>
```

Create a backend endpoint (e.g. `GET /wealthica/connect`) that:
1. Gets a fresh Wealthica user token (Step 1)
2. Encodes any app state into the `state` parameter (base64) so you can restore context after redirect
3. Renders the auto-submitting form above

### Connect URL parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `client_id` | Yes | Your Wealthica Client ID |
| `redirect_uri` | Yes | Where Wealthica redirects after completion. Must be pre-registered. |
| `state` | Recommended | Base64 string to restore your app state after redirect |
| `lang` | No | UI language: `en`, `fr`, `es`, `it` |
| `providers` | No | Comma-separated allow-list of providers, e.g. `questrade,td,demo` |
| `provider` | No | Skip provider selection, go directly to this provider's login |
| `theme` | No | `light` (default) or `dark` |
| `features` | No | Feature flags, e.g. `quick_retry` |

### URL variants for other flows

New connection:
`https://connect.wealthica.com/connect?client_id=...&redirect_uri=...`

Reconnect (update credentials for an existing account):
`https://connect.wealthica.com/reconnect/<INSTITUTION_ID>?client_id=...&redirect_uri=...`

Verify MFA / security question (without re-entering credentials):
`https://connect.wealthica.com/verify-mfa/<INSTITUTION_ID>?client_id=...&redirect_uri=...`

## Step 3 — Handle the redirect callback

Create a route at your redirect URI (e.g. `GET /wealthica/callback`). Wealthica redirects the user back with query parameters:

**On success:**
```
<REDIRECT_URI>?institution=<ID>&code=<ID>&provider=<TYPE>&state=<STATE>
```

**On failure:**
```
<REDIRECT_URI>?error_type=<CODE>&message=<MSG>&state=<STATE>&provider=<TYPE>&institution=<ID>
```

Your callback handler must:
1. Check if `error_type` is present — if so, show an error to the user using `message`.
2. If `institution` is present, store the institution ID in your database linked to the user.
3. Decode and restore app state from the `state` parameter.
4. Fetch the full institution data from the Wealthica API:

```
GET https://api.wealthica.com/institutions/<institutionId>
Headers:
  Authorization: Bearer <user_token>
```

### Callback query parameters reference

| Parameter | Present on | Description |
|-----------|-----------|-------------|
| `institution` | Both (on failure: only if created before the error) | The Wealthica institution ID |
| `code` | Success | Same as `institution` (for OAuth compliance) |
| `provider` | Both | The provider type string |
| `error_type` | Failure | Numeric error code |
| `message` | Failure | Human-readable error message |
| `force` | Failure | `true` if the user explicitly closed the widget |
| `state` | Both | Your app state passed in Step 2 |

---

# Constraints

- Token lifetime: 1 hour for API calls. The Connect session expires 10 minutes after token creation — always generate a fresh token right before redirecting.
- The redirect URI **must be pre-registered** with Wealthica. Contact Wealthica to register URIs for dev, staging, and production.
- Wealthica syncs institution data daily automatically. You can also trigger a manual sync via `POST /institutions/:id/sync`.
- For testing, use the `demo` provider: username `wealthica`, password `wealthica` for a successful connection.
- For mobile apps, register a custom scheme redirect URI (e.g. `com.myapp://wealthica/callback`) and handle it in your deep link handler.

# References (fetch these docs for the latest API details)

- Connect a user (full reference): https://wealthica.com/docs/connecting-a-user
- API reference: https://wealthica.com/docs/api
- Mobile support: https://wealthica.com/docs/mobile-support