### Frontend: Connect user and handle connection

Source: https://wealthica.com/docs/get-started

Frontend example: starts the Connect process on button click and handles the connection callback to retrieve and display the institution.

```javascript
// Get general Wealthica data  

const providers = await wealthica.providers.getList();  

  

// Start the Connect process when user clicks the Connect button  

document.getElementById('#connect').addEventListener('click', () => {  

  user.connect().onConnection(async (institutionId, data) => {  

    console.log('provider', data.provider);  

  

    const institution = await user.institutions.getOne(institutionId);  

    displayAccount(institution);  

  });  

}, false);  

```

--------------------------------

### Install the SDK via npm

Source: https://wealthica.com/docs/get-started

Install the Wealthica SDK package for use in a JS build system or NodeJS.

```bash
npm install --save wealthica-sdk-js
```

--------------------------------

### Backend: Get providers and institution data

Source: https://wealthica.com/docs/get-started

Backend example: retrieves general Wealthica data and user-specific institution data using the SDK's provider and institution methods.

```javascript
// Get general Wealthica data  

const providers = await wealthica.providers.getList();  

  

// Get user data via the `user` instance  

const institution = await user.institutions.getOne('INSTITUTION_ID');  

```

--------------------------------

### POST https://connect.wealthica.com/connect/demo

Source: https://wealthica.com/docs/connecting-a-user

Starts the Wealthica Connect process with a preselected provider (demo).

```APIDOC
## POST https://connect.wealthica.com/connect/demo

### Description
Starts the Wealthica Connect process with a preselected provider (demo).

### Method
POST

### Endpoint
https://connect.wealthica.com/connect/demo

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your team's Client ID.

#### Request Body (Form Data, x-www-form-urlencoded)
- **token** (string) - Required - The user token. See Authentication to see how to get the token.

### Request Example
```
POST https://connect.wealthica.com/connect/demo?client_id=YOUR_CLIENT_ID

Form Data (x-www-form-urlencoded):
token=USER_TOKEN
```

### Response
No response schema is provided in the source.
```

--------------------------------

### Load Wealthica SDK via CDN

Source: https://wealthica.com/docs/start-integration

HTML script tag to load the Wealthica SDK from a CDN. Use this as an alternative to npm installation for quick prototyping or static sites.

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

--------------------------------

### Get Providers via wealthica-sdk-js

Source: https://wealthica.com/docs/manage-providers

Initializes the Wealthica SDK and retrieves the list of published providers or a single provider by type. Requires `clientId` and `secret` from your Wealthica app.

```javascript
const wealthica = Wealthica.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

// Get all published providers
const providers = await wealthica.providers.getList();

// Get a single provider by type
const provider = await wealthica.providers.getOne('questrade');
```

--------------------------------

### Wealthica callback success redirect

Source: https://wealthica.com/docs/start-integration

Example of the redirect URI on successful connection. Wealthica appends query parameters including institution, code, provider, and state.

```http
<REDIRECT_URI>?institution=<ID>&code=<ID>&provider=<TYPE>&state=<STATE>
```

--------------------------------

### POST https://connect.wealthica.com/connect

Source: https://wealthica.com/docs/connecting-a-user

Starts the Wealthica Connect process for a user, allowing them to select a provider and connect their financial accounts.

```APIDOC
## POST https://connect.wealthica.com/connect

### Description
Starts the Wealthica Connect process for a user, allowing them to select a provider and connect their financial accounts.

### Method
POST

### Endpoint
https://connect.wealthica.com/connect

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your team's Client ID.

#### Request Body (Form Data, x-www-form-urlencoded)
- **token** (string) - Required - The user token. See Authentication to see how to get the token.

### Request Example
```
POST https://connect.wealthica.com/connect?client_id=YOUR_CLIENT_ID

Form Data (x-www-form-urlencoded):
token=USER_TOKEN
```

### Response
No response schema is provided in the source.
```

--------------------------------

### Provider data example for oAuth provider

Source: https://wealthica.com/docs/connecting-a-user

Example provider data from the /providers endpoint for an oAuth-enabled provider. It includes the client_id, authorize_url, and scopes needed to initiate the oAuth flow.

```json
{
  "name": "Questrade",
  "oauth": true,
  "client_id": "theclientid",
  "authorize_url": "https://login.questrade.com/oauth2/authorize",
  "scopes": ["read_acc"]
}
```

--------------------------------

### Wealthica callback failure redirect

Source: https://wealthica.com/docs/start-integration

Example of the redirect URI on failure. Includes error_type, message, state, provider, and institution parameters.

```http
<REDIRECT_URI>?error_type=<CODE>&message=<MSG>&state=<STATE>&provider=<TYPE>&institution=<ID>
```

--------------------------------

### ReactNative example: Integrate Wealthica Connect with AppAuth

Source: https://wealthica.com/docs/mobile-support

Shows how to use the Wealthica SDK JS in a ReactNative app with react-native-app-auth. The user.connect().onConnection() helper is not available, so this uses the oAuth 2.0 Authorization Code flow. Requires a registered redirect URL and a client ID. The authorize call uses skipCodeExchange: true and the authorizationCode is the institution ID.

```javascript
import Wealthica from 'wealthica-sdk-js/dist/wealthica.es5';  

import { authorize } from 'react-native-app-auth';  

import {URL} from 'react-native-url-polyfill';  

  

const clientId = 'YOUR_CLIENT_ID';  

const redirectUrl = 'com.yourapp://wealthica'; // need to be registered  

  

const wealthica = Wealthica.init({  

  clientId,  

  // Set authEndpoint or authorizer function similar to web app  

  authEndpoint: '/wealthica/auth',  

});  

  

// On button click  

const user = wealthica.login();  

const token = await user.fetchToken();  

// Or build connect URL via user.getConnectUrl()  

const authorizeUrl = 'https://connect.wealthica.com/connect/demo';  

  

// Now start the Wealthica Connect process  

try {  

  const result = await authorize({  

    serviceConfiguration: {  

      authorizationEndpoint: authorizeUrl,  

      tokenEndpoint: authorizeUrl, // required by AppAuth  

    },  

    clientId,  

    redirectUrl,  

    additionalParameters: { token, lang: 'es' },  

    skipCodeExchange: true,  

  });  

  

  const institutionId = result.authorizationCode;  

  sendToServer(institutionId);  

  const institution = await user.institutions.getOne(institutionId);  

  displayInstitution(institution);  

} catch (err) {  

  if (err.message !== 'Connection closed by the user') showError(err);  

}  

```

--------------------------------

### OAuth Connection Flow

Source: https://wealthica.com/docs/connecting-a-user

This snippet demonstrates the complete OAuth connection flow: building the authorization URL, starting the OAuth process, and handling the result by sending the code to the Wealthica API to create or update an institution.

```APIDOC
## OAuth Connection Flow

### Description
This flow describes how to connect an OAuth-enabled provider (e.g., Questrade) to the Wealthica API. It involves building the authorization URL, redirecting the user to the provider, and then using the returned code to create or update an institution connection.

### Prerequisites
- Provider data from the `/providers` endpoint with `oauth: true`.
- A registered Redirect URI with Wealthica, providing a `sub` string.

### Steps

#### Step 1: Build OAuth URL
- **redirect_uri**: `https://api.wealthica.com/oauth/redirect` (fixed)
- **client_id**: Use `provider.client_id` (or your custom Client Id if applicable).
- **response_type**: `code`
- **state**: Base64-encoded object containing `sub` (your registered sub) and optional `path` (e.g., `/connect`).
- **scope**: Space-separated list from `provider.scopes` (if provided).

#### Step 2: Start OAuth Process
- Redirect the user to the constructed `authorize_url` with the query parameters.

#### Step 3: Handle OAuth Result
- After user authorization, the OAuth result (code or error) is sent to your registered Redirect URI (with optional path).
- Your app must then send the code to the Wealthica API.

### API Calls

#### Create Institution (POST /institutions)
- **Description**: Create a new institution connection using the OAuth code.
- **Request Body**:
  - `name` (string) - Required - Provider name (e.g., "Questrade").
  - `type` (string) - Required - Provider type (e.g., "questrade").
  - `credentials` (object) - Required - Contains `code` (string) and optional `client_id` (string).

#### Update Institution (PUT /institutions/:id)
- **Description**: Update an existing institution connection with a new OAuth code.
- **Path Parameters**:
  - `id` (string) - Required - The ID of the existing connection.
- **Request Body**:
  - `credentials` (object) - Required - Contains `code` (string) and optional `client_id` (string).

### Example Code
```javascript
// STEP 1: Build oAuth URL
const OAUTH_REDIRECT_URI = "https://api.wealthica.com/oauth/redirect";
const OAUTH_SUB = 'myappdev';
const OAUTH_PATH = '/connect';

const oAuthState = { sub: OAUTH_SUB, path: OAUTH_PATH, ...additionalStateProps };
const state = encodeBase64(oAuthState);

const url = new URL(provider.authorize_url);
url.searchParams.append("client_id", provider.client_id);
url.searchParams.append("response_type", "code");
url.searchParams.append("state", state);
url.searchParams.append("redirect_uri", OAUTH_REDIRECT_URI);
if (provider.scopes) url.searchParams.append("scope", provider.scopes.join(" "));

// STEP 2: Start the oAuth process
openURL(url.href);

// STEP 3: Handling oAuth result
// After user completes, send code to Wealthica API
createInstitution({
  name: "Questrade",
  type: "questrade",
  credentials: { code: 'somecode', client_id: 'your own OAuth Client Id' }
});

// Or update existing
updateInstitution({
  id: 'existingconnectionid',
  credentials: { code: 'somecode', client_id: 'your own OAuth Client Id' }
});
```
```

--------------------------------

### Custom redirect URI with Wealthica Connect

Source: https://wealthica.com/docs/connecting-a-user

Custom redirect URI example: load the Wealthica Connect URL with a custom redirect_uri and state. After user finishes connecting an account, it will redirect to the success URL, or to the failure URL if connection failed or user closes the process. The Redirect URI must be registered first before it can be used.

```text
POST https://connect.wealthica.com/connect?client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.test/wealthica/callback&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64

Form Data (x-www-form-urlencoded):

token=USER_TOKEN
```

```text
https://myapp.test/wealthica/callback?institution=INSTITUTION_ID&code=INSTITUTION_ID&provider=PROVIDER&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64
```

```text
https://myapp.test/wealthica/callback?error_type=400&message=Invalid+credentials&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64&provider=PROVIDER&institution=INSTITUTION_ID
```

--------------------------------

### Initialize the Wealthica instance (Backend)

Source: https://wealthica.com/docs/get-started

Initialize the backend instance with your Client ID and Client Secret.

```javascript
const wealthica = Wealthica.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});
```

--------------------------------

### Get all transactions with pagination

Source: https://wealthica.com/docs/examples

Fetches all transactions for a given institution by paginating through the API. Requires the institution ID and a start date; uses an empty 'last' parameter for the first page and updates it with the last transaction ID of each page until no more pages remain.

```javascript
const transactions = [];  

const institutionId = '603522490d2b02001233a5d6';  

  

// Provide the date the financial institution account was created. If unsure,  

// pass in a very old date.  

const from = '2005-01-01';  

  

// Start off with an empty ?last, to query the very first page of transactions  

let last = '';  

  

// Fetch `100` transactions per page  

const limit = 100;  

  

while (true) {  

    const page = await user.transactions.getList({ institutionId, from, last, limit });  

  

    if (!page.length) break;  

  

    transactions.push(...page);  

    // Use this page's last transaction id to query the next page and so on  

    last = page[page.length - 1].id;  

}  

```

--------------------------------

### Initialize the Wealthica instance (Frontend)

Source: https://wealthica.com/docs/get-started

Initialize the frontend instance with only your Client ID, optionally authenticating with your server.

```javascript
const wealthica = Wealthica.init({
  clientId: 'YOUR_CLIENT_ID',
  // optional parameters for authenticating the Wealthica frontend instance with your server.
  // See Authentication section for a more detailed explanation.
  authEndpoint: '/wealthica/auth', // default value, need to accept POST
  auth: {
    params: { userId: 'LOGGED_IN_USER_ID' }, // custom params for authEndpoint
    headers: {}, // custom headers for authEndpoint
  },
});
```

--------------------------------

### Initialize Wealthica SDK and Open Connect Widget

Source: https://wealthica.com/docs/start-integration

JavaScript code to initialize the Wealthica SDK, log in the user, and open the Connect Widget. Handles connection success, errors, and lifecycle events. Replace '<CLIENT_ID>' with your actual client ID.

```javascript
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.
    });
}
```

--------------------------------

### Import the SDK from CDN

Source: https://wealthica.com/docs/get-started

Import the specific version or the latest version from the Wealthica CDN. The latest version may contain breaking changes.

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

```html
<script src="https://unpkg.com/wealthica-sdk-js/dist/wealthica.js"></script>
```

--------------------------------

### Fetch institution data with GET request

Source: https://wealthica.com/docs/start-integration

Use this GET request to retrieve the full institution object after the frontend sends the institutionId. The response includes updated data that Wealthica syncs daily. Requires a Bearer token for authorization.

```http
GET https://api.wealthica.com/institutions/<institutionId>

Headers:

  Authorization: Bearer <user_token>
```

--------------------------------

### GET /providers

Source: https://wealthica.com/docs/manage-providers

Retrieves the list of available providers with optional filters.

```APIDOC
## GET /providers

### Description
Retrieves the list of available providers. Supports filtering by group, publish status, connection class, and response format.

### Method
GET

### Endpoint
/providers

### Parameters
#### Query Parameters
- **group** (string) - Optional - Filter by provider group. Comma-separated. Values: `core` (Wealthica native connectors, excluding Yodlee/Plaid and crypto), `vezgo` (crypto providers), `yodlee`, `thirdparty` (alias for Yodlee).
- **unpublished** (boolean) - Optional - Filter by publish status. `false` = only published providers (default for the Connect widget), `true` = only unpublished providers. Omit to return all.
- **class** (string) - Optional - Filter by connection class: `api`, `oauth`, `scraper`.
- **format** (string) - Optional - Response format: `array` (recommended) or `object` (keyed by provider type).
- **include_providers** (string) - Optional - Comma-separated list of provider types to force-include regardless of other filters. Useful for including specific unpublished providers.

### Request Example
GET /providers?group=core&format=array

### Response
#### Success Response (200)
- **type** (string) - Unique provider identifier (e.g. `questrade`, `coinbase`)
- **name** (string) - Display name
- **outage** (boolean) - `true` if the provider is currently experiencing an outage
- **outage_incident_link** (string) - URL with details about the outage (when applicable)
- **unpublished** (boolean) - `true` if the provider is not publicly available
- **instructions** (object) - Localized connection instructions (`en`, `fr`, `pt`)
- **note** (string) - Internal note about the provider

#### Response Example
{
  "type": "questrade",
  "name": "Questrade",
  "outage": false,
  "outage_incident_link": null,
  "unpublished": false,
  "instructions": {
    "en": "...",
    "fr": "...",
    "pt": "..."
  },
  "note": "..."
}
```

--------------------------------

### Log in a user (Backend)

Source: https://wealthica.com/docs/get-started

Log in a user to create a user instance for requesting user data.

```javascript
const user = wealthica.login('USERNAME');
```

--------------------------------

### POST [Webhook] SyncInstitution

Source: https://wealthica.com/docs/webhooks

Documentation for the SyncInstitution webhook, which is sent via POST when an account successfully syncs.

```APIDOC
## POST [Webhook] SyncInstitution

### Description
A `SyncInstitution` webhook is sent to your receiving endpoint via a `POST` when an account successfully syncs. The webhook is triggered at the end of the sync process if it is successful.

### Method
POST

### Endpoint
Your webhook URL (provided by you)

### Headers
- **x-client-id** (string) - Required - Your client app id, used to identify which of your applications the event belongs to.

### Request Body
- **hook** (string) - Required - The webhook type, value: `SyncInstitution`.
- **user** (object) - Required - Contains user information.
  - **id** (string) - Required - User ID.
  - **loginName** (string) - Required - User login name.
- **institution** (object) - Required - Contains institution information.
  - **id** (string) - Required - Institution ID.
  - **name** (string) - Required - Institution name.
  - **type** (string) - Required - Institution type.

### Request Example
```json
{
  "hook": "SyncInstitution",
  "user": { "id": "user123", "loginName": "john.doe" },
  "institution": { "id": "inst456", "name": "Bank of Example", "type": "bank" }
}
```

### Response
No response body is documented. The webhook is sent to your endpoint; no response schema is provided in the source.

```

--------------------------------

### POST https://connect.wealthica.com//INSTITUTION_ID

Source: https://wealthica.com/docs/connecting-a-user

Starts the Wealthica Connect process with a custom redirect URI and state parameter.

```APIDOC
## POST https://connect.wealthica.com//INSTITUTION_ID

### Description
Starts the Wealthica Connect process with a custom redirect URI and state parameter.

### Method
POST

### Endpoint
https://connect.wealthica.com//INSTITUTION_ID

### Parameters
#### Path Parameters
- **INSTITUTION_ID** (string) - Required - The institution ID.

#### Query Parameters
- **client_id** (string) - Required - Your team's Client ID.
- **redirect_uri** (string) - Optional - The URI to redirect to after the process is finished. This must match one of your team's registered Redirect URIs.
- **state** (string) - Optional - An opaque string containing your application state, to maintain application state between redirects (in the oAuth process).

#### Request Body (Form Data, x-www-form-urlencoded)
- **token** (string) - Required - The user token. See Authentication to see how to get the token.

### Request Example
```
POST https://connect.wealthica.com//INSTITUTION_ID?client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.test/wealthica/callback&state=APP_STATE

Form Data (x-www-form-urlencoded):
token=USER_TOKEN
```

### Response
No response schema is provided in the source.
```

--------------------------------

### Import the SDK (CommonJS and ESX)

Source: https://wealthica.com/docs/get-started

The same package is used for both frontend and backend. CommonJS uses require, ESX uses import.

```javascript
const Wealthica = require('wealthica-sdk-js');
```

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

--------------------------------

### Connect User with Preselected Provider

Source: https://wealthica.com/docs/connecting-a-user

Connect URL with a preselected provider (demo). Requires client_id and token as form data.

```http
POST https://connect.wealthica.com/connect/demo?client_id=YOUR_CLIENT_ID  

Form Data (x-www-form-urlencoded):  

token=USER_TOKEN  
```

--------------------------------

### Preselect a provider with user.connect

Source: https://wealthica.com/docs/connecting-a-user

Preselect a provider by passing the provider type to .connect(). This skips the provider selection step and goes straight to the credentials form. The provider type is obtained from the Provider object.

```javascript
document.getElementById('#connect_demo').addEventListener('click', () => {  

  user.connect({ provider: 'demo' }).onConnection((institutionId, data) => {  

    console.log('provider', data.provider);  

    console.log('Demo connection success:', institutionId)  

  });  

}, false);  


```

--------------------------------

### Fetch institution data (GET /institutions/<institutionId>)

Source: https://wealthica.com/docs/start-integration

API call to retrieve full institution data after a successful connection. Requires the user token as a Bearer token in the Authorization header.

```http
GET https://api.wealthica.com/institutions/<institutionId>

Headers:
  Authorization: Bearer <user_token>
```

--------------------------------

### oAuth integration steps for connecting a user

Source: https://wealthica.com/docs/connecting-a-user

Complete oAuth integration workflow for providers with oauth: true. Builds the authorization URL using the provider's client_id and authorize_url, opens it, then handles the returned code by either creating a new institution via POST /institutions or updating an existing one via PUT /institutions/:id. The redirect_uri is always https://api.wealthica.com/oauth/redirect and the state includes the registered sub and optional path.

```javascript
// STEP 1: Build oAuth URL

const OAUTH_REDIRECT_URI = "https://api.wealthica.com/oauth/redirect";
const OAUTH_SUB = 'myappdev';

// If you have different receiving paths for different flows (e.g. connect vs reconnect), you can
// provide a path. It will be concatenated with your registered URI.
// E.g. https://dev.myapp.com/connect, https://dev.myapp.com/reconnect/someaccountid
const OAUTH_PATH = '/connect';

// Prepare oAuth state.
// The Wealthica OAuth Redirection service will redirect based on your `sub` and (optional) `path`.
// You can still pass your client state info here.
const oAuthState = {
  sub: OAUTH_SUB,
  path: OAUTH_PATH,
  ...additionalStateProps,
};
const state = encodeBase64(oAuthState);

// Build the URL
const url = new URL(provider.authorize_url);
url.searchParams.append("client_id", provider.client_id);
url.searchParams.append("response_type", "code");
url.searchParams.append("state", state);
url.searchParams.append("redirect_uri", OAUTH_REDIRECT_URI);
if (provider.scopes) url.searchParams.append("scope", provider.scopes.join(" "));

// STEP 2: Start the oAuth process
// User will be presented with the provider's oAuth page (Questrade in this example).
// E.g. https://login.questrade.com/oauth2/authorize?client_id=theclientid...
openURL(url.href);

// STEP 3: Handling oAuth result
// After user completes the process, the oAuth result will be passed to your Redirect URI.
// E.g. https://dev.myapp.com/connect?code=somecode&state=thestate...

// Your app will then be responsible to send the code to the Wealthica API. Either:

// Send a POST to `/institutions` endpoint to create a new connection
createInstitution({
  name: "Questrade",
  type: "questrade",
  credentials: {
    code: 'somecode',
    client_id: 'your own OAuth Client Id', // optional, you should not need this in most cases.
  }
});

// Or send a PUT to `/institutions/:id` to update the existing connection
updateInstitution({
  id: 'existingconnectionid',
  credentials: {
    code: 'somecode',
    client_id: 'your own OAuth Client Id', // optional, you should not need this in most cases.
  }
})
```

--------------------------------

### Get Providers via API

Source: https://wealthica.com/docs/manage-providers

Retrieves the list of providers. The `group` parameter filters by provider group (e.g., `core`), and `format=array` returns the response as an array. Other query parameters include `unpublished`, `class`, and `include_providers`.

```http
GET /providers?group=core&format=array
```

--------------------------------

### Open Wealthica Connect Widget with user.connect()

Source: https://wealthica.com/docs/connecting-a-user

Attaches a click handler to the #connect element that calls user.connect() to open the Wealthica Connect Widget. The onConnection callback receives the institutionId and data, logs the provider, sends the institution id to the server, and fetches institution data to display.

```javascript
document.getElementById('#connect').addEventListener('click', () => {  

  user.connect().onConnection(async (institutionId, data) => {  

    console.log('provider', data.provider);  

  

    // Send the institution id to your server  

    sendToServer('/some-route', institutionId);  

    // Request institution data to display in the page  

    const institution = await user.institutions.getOne(institutionId);  

    displayAccount(institution);  

  });  

}, false);  
```

--------------------------------

### Connect User via Standard Connect URL

Source: https://wealthica.com/docs/connecting-a-user

Standard Wealthica Connect URL to connect a user. Requires client_id and token as form data.

```http
POST https://connect.wealthica.com/connect?client_id=YOUR_CLIENT_ID  

Form Data (x-www-form-urlencoded):  

token=USER_TOKEN  
```

--------------------------------

### Customize Connect Widget with pre-created iframe

Source: https://wealthica.com/docs/connecting-a-user

Customize the Connect Widget by pre-creating an iframe with name 'wealthica-connect-widget' anywhere in the page. The .connect() method will load the widget inside that element instead of appending a new one at the root of the body. The JS SDK adds display: block when opening and display: none when closing.

```html
<html>  

<head>  

  <style>  

    iframe[name='wealthica-connect-widget'] {  

      border: 1px solid gray;  

      width: 300px;  

      height: 500px;  

      display: none;  

    }  

  </style>  

</head>  

<body>  

  <nav>Nav bar</nav>  

  <section>  

    <h1>Connect your account</h1>  

  

    <button id="connect">Connect</button>  

    <iframe name='wealthica-connect-widget'></iframe>  

  </section>  

</body>  

</html>  


```

--------------------------------

### POST /connect

Source: https://wealthica.com/docs/connecting-a-user

Initiates the Wealthica Connect process with a custom redirect URI. The user is redirected to the provided redirect_uri after the connection process completes.

```APIDOC
## POST /connect

### Description
Initiates the Wealthica Connect process with a custom redirect URI. The user is redirected to the provided redirect_uri after the connection process completes.

### Method
POST

### Endpoint
https://connect.wealthica.com/connect

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your client ID.
- **redirect_uri** (string) - Required - The URI to redirect to after the connection process.
- **state** (string) - Required - Application state before connection, base64 encoded.

#### Request Body (Form Data, x-www-form-urlencoded)
- **token** (string) - Required - User token.

### Request Example
POST https://connect.wealthica.com/connect?client_id=YOUR_CLIENT_ID&redirect_uri=https://myapp.test/wealthica/callback&state=APP_STATE_BEFORE_CONNECTION_IN_BASE64

Form Data (x-www-form-urlencoded):
token=USER_TOKEN

### Response
#### Success Redirect (302)
Redirects to the redirect_uri with the following query parameters:
- **institution** (string) - The Wealthica institution id.
- **code** (string) - Same as institution.
- **provider** (string) - The provider.
- **state** (string) - The application state passed.

#### Failure Redirect (302)
Redirects to the redirect_uri with the following query parameters:
- **error_type** (number) - The connection error code.
- **message** (string) - The connection error message.
- **state** (string) - The application state passed.
- **provider** (string) - The provider.
- **institution** (string) - The institution id if created before error.

### Notes
- The redirect_uri must be registered before use.
- The redirect_uri can be a custom URI.
```

--------------------------------

### user.connect() - Direct to a Single Provider

Source: https://wealthica.com/docs/manage-providers

SDK method to directly connect to a single provider.

```APIDOC
## user.connect() - Direct to a Single Provider

### Description
Skips the provider selection screen and goes directly to a specific provider's login.

### Method
SDK Method

### Endpoint
user.connect()

### Parameters
#### Request Body
- **provider** (string) - Optional - The provider type identifier to go directly to.

### Request Example
user.connect({
  provider: 'td', // go directly to TD login
});
```

--------------------------------

### AI Agent Prompt for Popup Widget Integration

Source: https://wealthica.com/docs/start-integration

A comprehensive prompt for an AI coding agent to integrate Wealthica Connect using the Popup Widget flow. It specifies backend endpoint creation, frontend SDK usage, and security rules. Replace placeholders like [REPLACE: ...] with actual values.

```markdown
# 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.  

    });  

}  

```  


```

--------------------------------

### user.connect() - Include Specific Providers

Source: https://wealthica.com/docs/manage-providers

SDK method to include specific providers in the Connect widget.

```APIDOC
## user.connect() - Include Specific Providers

### Description
Shows only a specific set of providers in the Connect widget. This is an allow-list.

### Method
SDK Method

### Endpoint
user.connect()

### Parameters
#### Request Body
- **providers** (array) - Optional - Array of provider type identifiers to show. Note: ignored if `provider` (singular) is also passed.

### Request Example
user.connect({
  providers: ['wise', 'stockchase'], // only show these providers
});
```

--------------------------------

### Frontend token acquisition with backend auth endpoint

Source: https://wealthica.com/docs/authentication

Frontend clients use the SDK with an authEndpoint (default '/wealthica/auth') and pass the username in auth.params. The backend must implement that endpoint, using the secret to obtain a token and return it to the frontend.

```javascript
const wealthica = Wealthica.init({  
  clientId: 'YOUR_CLIENT_ID',  
  authEndpoint: '/wealthica/auth', // default value, your server should implement this endpoint  
  auth: {  
    params: { username: 'USERNAME_FROM_YOUR_SYSTEM' }  
  }  
});  

const user = wealthica.login();  
const token = await user.getToken();  

```

```javascript
const wealthica = Wealthica.init({  
  clientId: 'YOUR_CLIENT_ID',  
  secret: 'YOUR_CLIENT_SECRET',  
});  

app.post('/wealthica/auth', async (req, res) => {  
  // Replace with your own authentication  
  const { username } = req.body;  
  const user = wealthica.login(username);  

  res.json({ token: await user.getToken() });  
});  

```

--------------------------------

### Backend token acquisition (SDK and curl)

Source: https://wealthica.com/docs/authentication

Backend clients can obtain a user token using the Wealthica SDK (JavaScript) or via curl. Both require the clientId and secret, and the loginName header/parameter.

```javascript
const wealthica = Wealthica.init({  
  clientId: 'YOUR_CLIENT_ID',  
  secret: 'YOUR_CLIENT_SECRET',  
});  

const user = wealthica.login('USERNAME_FROM_YOUR_SYSTEM');  
const token = await user.getToken();  

```

```shell
curl '{WEALTHICA_API_URL}/auth/token' \  
  -X POST \  
  -H 'loginName: USERNAME_FROM_YOUR_SYSTEM' \  
  -H 'Content-Type: application/json' \  
  -d '{  
      "clientId": "YOUR_CLIENT_ID",  
      "secret": "YOUR_CLIENT_SECRET"  
  }'  

```