# Investor portal

Source: https://docs.settlemint.com/docs/concepts/operating/investor-portal
What your investors see in the Investor portal, from sign-in to the dashboard, and how the portal runs on your own domain with your organisation's branding.

The Investor portal is the web app your investors use to hold, buy and trade the assets your organisation issues. It is a separate app from the operator Console, with its own sign-in, its own session and its own web address. It runs on your domain and shows your theme: your logo, sign-in page images, browser icons, fonts and colours. [Your branding](#your-branding) names the cases where a global theme or the default theme shows instead. This page is for the organisation that runs the portal. Investors read the [investor guide](#the-investor-guide).

The portal reads its data from the Platform API, the same API the Console and your own integrations call, and holds no sample data. An area with nothing in it shows an empty state that says so, such as "No open offerings" in Invest.

Your organisation keeps its controls over every holding an investor sees here. A holder of the token's Custodian role can freeze a balance or force a transfer, as [Transfer-Path Compliance](https://docs.settlemint.com/docs/concepts/compliance-and-identity/transfer-path-compliance) describes, and a bank rail recall can take back tokens minted against a payment the bank reversed, as [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers) describes.

## What an investor goes through [#what-an-investor-goes-through]

On a first visit, an investor goes through up to six steps before the dashboard opens. On a later visit, sign-in and the second factor are all that remain, unless a new trading document version or an enforced two-factor rule adds a step again.

1. **Sign in.** Your organisation adds investors in the Console with "Create or invite user" on the [Users](https://docs.settlemint.com/docs/console/participants/users) page. The portal has no sign-up page. With an identity provider configured, the platform refuses sign-up from the portal. Without one, the Platform API accepts email sign-up through the portal's address, and such an account has no active organisation until a platform administrator makes one active. Its sign-in page tells investors that their identity manager gives them access. Identity manager is the Console role that registers identities and onboards users. An investor signs in with email and password or with a passkey. The portal offers no sign-in through your identity provider. "Forgot your password?" sends a link to set a new password. A visitor who opens an investor page without a session goes to sign-in and returns to the page they asked for afterwards.
2. **Second factor.** When the account has two-factor authentication, a dialog asks for a 6-digit code from an authenticator app, an email or a text message, depending on the methods the account has.
3. **Wallet setup.** The investor pages open only for a session with an active organisation and an investor participant that holds a wallet. A participant is the account the investor acts as in your organisation. An investor without one goes to the "Wallet setup" page.
   - When your organisation offers more than one wallet type, the investor picks one. An embedded wallet is created with the investor's sign-in and needs nothing installed. A browser wallet is the investor's own wallet, which they prove with one signature. With a managed account, your organisation creates and holds the wallet. The embedded wallet appears only when the deployment has its embedded wallet service configured.
   - The investor then creates the wallet, or connects their own and signs a message to prove it. An investor who already has a suitable participant on the platform picks it instead.
4. **Trading document acceptance.** When your organisation has published trading terms or a risk disclosure, the portal shows "Review the current trading documents". The investor ticks each current version and selects "Accept and continue". The portal records the acceptance and continues.
5. **Two-factor setup.** When the deployment requires two-factor authentication and the investor has not set it up, the portal sends every investor page to the Security page until the investor sets it up. When trading documents also wait for acceptance, the acceptance screen comes first.
6. **Dashboard.** The dashboard opens with the sidebar beside it.

Two account states stop the journey and offer no retry, because the investor cannot change them. A session with no active organisation shows "No active organisation". A platform administrator must make an organisation active on the account, and until then the investor can open Profile and Security or sign out. The onboarding screen "This organisation has not chosen an investor wallet yet" shows in two cases: your organisation has not designated an investor wallet provider, or it designated the embedded wallet and the deployment has no embedded wallet service configured.

You publish the trading documents in the Console, under [Trading terms and risk disclosures](https://docs.settlemint.com/docs/console/organisation-settings/general#publish-trading-terms-and-risk-disclosures). Publish both kinds together. Once one kind has a version in force, no investor passes the acceptance screen until the other kind is published too. A new major version always asks investors to accept again. A new version within the same major version asks again only when you tick "Require participants to accept this version again". The portal shows the acceptance screen again the next time it reads the investor's acceptance status.

The platform also checks acceptance on the trading venue and on withdrawals. While an acceptance is outstanding, it refuses to place, amend, sign or cancel an order, and it refuses to create a withdrawal. Other operations, such as a purchase in an offering through Invest, are held back by the portal's acceptance screen only.

## The dashboard and the areas [#the-dashboard-and-the-areas]

The dashboard has three shapes. Before the investor's on-chain identity is registered, it shows "Register your identity to hold and trade assets" with the steps that remain. The on-chain identity is the record that regulated assets check before a wallet can receive them. With a registered identity and no holdings, it shows "You hold no assets yet." with a "Browse offerings" button that opens Invest. With holdings, it shows "Key figures" and the portfolio. Each shape includes "Needs attention", which lists what waits for the investor.

![Investor portal dashboard with the sidebar, key figures and Needs attention](https://docs.settlemint.com/docs/screenshots/portal-dashboard-overview.light.en.webp)

[Screenshot] The sidebar on the left lists Dashboard, Actions and Activity, then Portfolio, Invest and the other areas under Wealth, then Contacts and Watchlists under Personal.

The dashboard shows key figures, a Needs attention panel and the portfolio.

The sidebar leaves out an area your organisation does not offer, rather than greying it out. Dashboard, Actions and Activity sit at the top without a group label.

| Area | What the investor does there | Sidebar group | When it appears |
| --- | --- | --- | --- |
| Dashboard | Sees what needs attention, the portfolio value and recent activity | Unlabelled | Always |
| Actions | Completes tasks that wait for them, such as casting a vote or accepting a transfer | Unlabelled | Always, with a count of pending actions |
| Activity | Looks back at what happened on the account | Unlabelled | Always |
| Portfolio | Sees holdings, their value and the income they pay, such as dividends and interest | Wealth | Always |
| Invest | Buys into an offering that your organisation has opened | Wealth | Always. It shows "No open offerings" when nothing is open to the investor |
| Trading | Buys from and sells to other investors after issuance | Wealth | When the deployment turns on the Secondary market module and your organisation has deployed the trading venue add-on |
| Announcements | Reads the notices a venue publishes, including those no longer on display, and filters them by category, market and date | Wealth | Under the same two conditions as Trading |
| Settlements | Swaps assets with another party, where neither side's transfer completes without the other | Wealth | When your organisation has deployed the XvP settlement add-on |
| Votes | Votes on proposals for the assets they hold | Wealth | When your organisation has deployed the token governance add-on |
| Contacts | Keeps the wallets of counterparties for reuse | Personal | Always |
| Watchlists | Follows assets | Personal | Always |
| Withdrawal destinations | Sees the wallets that withdrawals can go to | Personal | When the deployment turns on the Self-custody module |

The account menu holds Profile, My participants, On-chain identity, Security, Bank accounts when your organisation offers bank payouts, and Notifications, then the theme, the language, Documentation when the investor guide is configured, Keyboard shortcuts, Report an issue and Sign out. The language menu lists the languages your organisation enables in the Console, from the same ten, and shows only when more than one is enabled. Arabic is laid out right to left.

The portal's paths match the Console's paths, such as `/wealth/portfolio` and `/personal/contacts`. The breadcrumb starts with the sidebar group, and the group name is a link. Wealth opens Portfolio and Personal opens Contacts, the first area of each group, which every investor sees.

## When something is unavailable [#when-something-is-unavailable]

The portal tells the investor what went wrong and offers only the actions that can change it.

| What the investor sees | Cause | What the screen offers |
| --- | --- | --- |
| "Platform unreachable" | The session read failed with a server error or took longer than 10 seconds, or a read the portal needs to admit the investor failed | Retry |
| "The platform is unreachable" on sign-in | The sign-in request got no answer | The sign-in button reads Retry |
| "Page not found" | The address points to nothing the investor may see, for example a malformed id, an unknown add-on address or a record the investor may not see | Go back, Go home |
| "Not available" | A direct link to an area your organisation does not offer | Go to dashboard, Go back |
| "Couldn't check your access" | The portal could not read whether the area is available | Try again, Go to dashboard |
| "XvP settlement isn't set up" | A Settlements link while your organisation has not deployed the XvP settlement add-on | Go to dashboard, Go back |
| "Unable to load this section" | One section's read failed. The rest of the page keeps working. The platform's own title replaces this one when the error has one | Try again, unless the platform refused the read or marked it as not retryable |
| "Your session is about to expire" | The organisation's idle sign-out is 60 seconds away | Stay signed in |

A section read that fails for a temporary reason is retried up to two times with a growing delay, and then the section shows as unavailable.

The portal does not retry a read that the platform refused. It also does not send that read again for five minutes, even when the investor switches windows or returns to the page. A section error shows a reference ID that the investor can pass to your support team.

You set the idle sign-out period in the "Idle sign-out" row of the Security section on the Console's [General](https://docs.settlemint.com/docs/console/organisation-settings/general) page. An idle sign-out in one portal tab also signs the investor out in their other portal tabs.

## Your domain [#your-domain]

An investor's portal session belongs to the portal's domain, and the Console does not accept it. You cannot embed the portal inside a page of another site, because it refuses to load in a frame.

The Investor portal is its own workload in the Helm chart, switched on with `investorPortal.enabled`, and off by default. You give it a public URL in `global.dalpApp.env.INVESTOR_PORTAL_URL`. The chart passes that URL to the portal and lists it as a portal origin of the Platform API, so the platform accepts sign-ins from that host. The Console's account menu then shows an "Investor portal" item to every Console user, and the item opens the portal in a new tab. Without a valid `http` or `https` portal URL, the Console shows no item.

The investor's browser never calls the platform directly. It sends every platform call to the portal's own origin, and the portal server forwards `/api` and `/dalp` paths to the private platform address in `DAPI_INTERNAL_URL`. The session cookie therefore belongs to the portal's domain wherever the platform runs. The Console accepts only a session that its own sign-in issued.

The portal forwards a sign-up call like any other, so the identity provider rule in [What an investor goes through](#what-an-investor-goes-through) applies to it. When the Console signs in only through an identity provider, an account that administers the platform or an organisation cannot sign in to the portal. It signs in to the Console through the identity provider.

The forwarding route removes the forwarding headers the browser sent and passes on the client address only from the proxy in front of the portal. The deployment names that proxy in `TRUSTED_PROXY_PROFILE` as `envoy`, `nginx` or `openshift`, and any other value counts as none. A read that loses its connection is retried once, and a request with a body is not retried. When the platform does not answer, the call gets HTTP 502 with the code `UPSTREAM_UNAVAILABLE`. A method the platform does not serve, such as `TRACE` or `PROPFIND`, gets HTTP 405 with the code `METHOD_NOT_ALLOWED` and an `Allow` header that lists the methods it does serve. Event streams pass through as streams. [Deploy browser apps with user sessions](https://docs.settlemint.com/docs/deployment/install/browser-apps) has the Helm values and the OpenShift Route setup.

## Install the portal as an app [#install-the-portal-as-an-app]

An investor can install the portal from a browser that supports installing web apps, such as Chrome on Android, or Safari on iOS through Share, then Add to Home Screen. The portal then opens in its own window from an icon on the home screen or desktop. DALP builds no separate iOS or Android app, because the installed portal is the same portal: the investor signs in, enters the second factor and signs wallet requests on the same pages as in the browser.

The app takes its name, icon and colour from your theme. The name is the logo's alternative text, with "DALP Investor portal" when you set none. The icons are the theme's browser icons, and the colour behind the icon while the app opens is the light background colour. An organisation that sets no browser icons shows the default icons on the home screen, so upload them on the Console's [Theme](https://docs.settlemint.com/docs/console/organisation-settings/theme) page. Installing needs an https address, which your portal URL already is in production.

The device keeps only the portal's script, style and font files, so a repeat visit loads them without a download. It keeps no page, no platform answer and no account data. The portal does not work offline: with no connection, the investor sees the browser's own offline message, and no order or other request goes through until the connection returns. A sign-in, second factor or wallet signature is never served from the device, so an installed portal cannot show a stale signed-in page.

## Your branding [#your-branding]

The portal applies the theme your organisation sets on the Console's [Theme](https://docs.settlemint.com/docs/console/organisation-settings/theme) page and keeps no copy of its own. A theme change reaches an investor's open portal the next time the page loads.

- **Logo.** The sidebar shows the horizontal logo, and the icon when the sidebar is collapsed. The sign-in page uses the sign-in logo when you set one.
- **Sign-in page images.** The sign-in page shows the overlay and background images you set.
- **Browser icons.** The favicons, the home-screen icon and the icon of the [installed app](#install-the-portal-as-an-app) come from the theme.
- **Typography and colours.** The sans-serif and monospace faces and the light and dark colours style every page.
- **Titles.** The browser tab title, the home-screen app title and the installed app's name use the logo's alternative text. Without it, the tab reads "DALP Investor portal" and the home-screen title reads "SettleMint", so set the alternative text.

When a platform administrator turns on a global theme, every page shows the global theme instead of your organisation's theme, before and after sign-in. Without a global theme, signed-out screens such as sign-in show your theme only when the deployment has a single organisation. In a deployment with more than one organisation they show the default theme, and your theme appears after sign-in. When the theme read takes longer than 2 seconds or fails, the portal draws the default theme and reads the theme again on the next navigation.

## The investor guide [#the-investor-guide]

The investor guide is a separate documentation site for investors. It has six pages: "Investor guide", "Sign in and set up your account", "Deposit by bank transfer", "Bank payments in Transfers", "Bank accounts for payouts" and "Read your bank cash-outs". The Helm value `investorDocs.enabled`, off by default, deploys the guide beside the portal and routes `/docs` on the portal's host to it.

The portal links to the guide only when you set `INVESTOR_GUIDE_URL` in `investorPortal.env`. The value is a path on the portal's host, such as `/docs`, or an `http` or `https` address, and the portal ignores any other value. With a valid value, the account menu shows "Documentation". The information icon next to a term, on screens such as the portfolio, offerings with vesting or a refund window, the trading venue and settlements, then adds a "Read the docs" link below its one-line explanation.

Other information icons, such as those that explain a figure or a form field, carry no link. Without the value, the menu item and the links are hidden, and the explanations stay. Each link opens the guide in a new browser tab.

## You should see [#you-should-see]

- The portal's public URL opens a sign-in page that shows your logo and sign-in images, and the browser tab shows your title. In a deployment with more than one organisation and no global theme, they appear only after sign-in.
- `/manifest.webmanifest` on the same address lists the name and icons that an installed app uses, and the portal installed from a phone browser shows its home-screen icon.
- Signed in as an investor, the sidebar lists only the areas your organisation offers.
- A direct link to another area shows "Not available".
- The Console's account menu shows "Investor portal" and opens this host.

## Related pages [#related-pages]

- [Delegated authority](https://docs.settlemint.com/docs/concepts/compliance-and-identity/delegated-authority): the acting-as model the portal shares with the Console.
- [Users](https://docs.settlemint.com/docs/console/participants/users): adding investors.
- [Portfolio](https://docs.settlemint.com/docs/console/my-assets/portfolio): the holder operations an investor starts from a holding.
- [Bank transfers](https://docs.settlemint.com/docs/concepts/operating/investor-portal-bank-transfers): deposits by bank transfer, which an investor starts from Deposit in Portfolio.