Overview

Mesh APIs allow client applications to connect users to their accounts across brokerages, centralized exchanges, and self-custody wallets. Mesh APIs handle credential validation, multi-factor authentication, and error handling when connecting to each account. After an end-user authenticates with their account credentials, clients will be passed authentication tokens to provide access to the account which allows client applications to read account information such as holdings, transactions, and balances, and initiate trades and transfers on behalf of the end-user.

Using Mesh APIs, you can easily connect with the following types of accounts:

Brokerage firms
Centralized exchanges
Self-custody wallets
NFT marketplaces

You can easily fetch information from those accounts, including:

Holdings — get portfolio holdings of the connected financial institution accounts (stocks, cryptocurrencies, or NFTs)
Balance — get fiat balances of the connected financial institution accounts
Transaction History — get history of orders and other transactions

Additionally, you can perform write functions, including:

Trading — Execute buy and sell orders of equities and digital assets
Transfers — Exchange to wallet or Wallet to Exchange digital asset transfers

Introduction

The fastest and easiest way to get started with Mesh is by using our Quickstart Guide, or cloning the Quickstart React app. You’ll need to generate API keys, which are accessible after signing up for Mesh (you can generate both Sandbox and Production keys). You should also add any 'Allowed callback URLs' for your local, staging, and production environments to allow the Link SDK to load correctly (note: you should add full URLs like http://localhost:3000/settings/user).

How it works

You will use both server and client-side components to communicate with Mesh APIs.

Call /api/v1/cataloglink to create a link URL to create a temporary and unique URL that your user can connect their account.
Pass the iFrameURL to the appropriate Link SDK
Your user will be able to filter and search for the account they want to connect. Mesh will manage the authentication flow and handle MFAs for all supported integrations.
You will receive an auth_token in the return method after a user successfully enters their credentials.
You can stores the auth_token (and refresh_token) for use in subsequent server requests

The first step is to create a link URL by making a /api/v1/cataloglink request and passing in the required configurations. This link URL is a temporary, one-time-use URL that authenticates your app with Mesh Link SDKs, our frontend module.

curl -X GET https://sandbox-integration-api.getfront.com/api/v1/cataloglink
-H 'Content-Type: application/json' \
-H 'X-Client-Id: CLIENT_ID' \
-H 'X-Client-Secret: CLIENT_SECRET' \
--url-query userId=client_user_id \\ Your internal GUID for the user \\
--url-query callbackUrl=https://domainname.com/

{
"content": {
"url": "https://web.getfront.com/broker-connect?auth_code={authCode}",
"iFrameUrl": "https://web.getfront.com/b2b-iframe/{clientId}/broker-connect?auth_code={authCode}"
},
"status": "ok",
"message": ""
}

Once you have the iFrameUrl, you can use it to initialize the Mesh Link SDK. Mesh Link SDKs are a drop-in client-side module available for web, iOS, and Android that handles the authentication process. This is what your users use to connect to their accounts.

import React, { useEffect, useState } from 'react'
import {
  FrontConnection,
  FrontPayload,
  createFrontConnection
} from '@front-finance/link'
import { clientId } from '../utility/config'

export const FrontComponent: React.FC<{
  iframeLink?: string | null
  onSuccess: (authData: FrontPayload) => void
  onExit?: (error?: string) => void
}> = ({ iframeLink, onSuccess, onExit }) => {
  const [frontConnection, setFrontConnection] =
    useState<FrontConnection | null>(null)

  useEffect(() => {
    setFrontConnection(
      createFrontConnection({
        clientId: clientId,
        onBrokerConnected: authData => {
          console.info('[FRONT SUCCESS]', authData)
          onSuccess(authData)
        },
        onExit: (error?: string) => {
          if (error) {
            console.error(`[FRONT ERROR] ${error}`)
          }

          onExit?.()
        }
      })
    )
  }, [])

  useEffect(() => {
    if (iframeLink) {
      frontConnection?.openPopup(iframeLink)
    }

    return () => {
      if (iframeLink) {
        frontConnection?.closePopup()
      }
    }
  }, [frontConnection, iframeLink])

  return <></>
}

On successful authentication, you will be provided the auth_token (and in most cases refresh_token) that can be used in subsequent calls.

Making API Calls

Now that we've gone over the Link experience and token exchange process, we can explore what happens when you make an API call. As an example, we’ll look at the call to /api/v1/holdings/get, which retrieves the account holdings for the connected account. The call is straightforward and uses the auth_token and broker type.

/api/v1/holdings/get

curl -X POST https://sandbox-integration-api.getfront.com/api/v1/holdings/get \
	-H 'Content-Type: application/json' \
	-H 'X-Client-Id: CLIENT_ID' \
	-H 'X-Client-Secret: CLIENT_SECRET' \
	-d '{
				"authToken": "front_auth_token"
				"type": "robinhood"
			}'

/api/v1/holdings/get response

{
  "content": {
    "status": "succeeded",
    "equityPositions": [
      {
        "symbol": "AAPL",
        "amount": 3,
        "costBasis": 109
      },
      {
        "symbol": "F",
        "amount": 27,
        "costBasis": 7.05791
      }
    ],
    "notSupportedEquityPositions": [
      {
        "symbol": "CUSIP38259P508",
        "amount": 1
      }
    ],
    "notSupportedCryptocurrencyPositions": [],
    "cryptocurrencyPositions": [
      {
        "symbol": "DOGE",
        "amount": 1503,
        "costBasis": 0.033
      },
      {
        "symbol": "BTC",
        "amount": 3.0001672,
        "costBasis": 18000
      }
    ],
    "nftPositions": [],
    "optionPositions": [],
    "type": "robinhood",
    "accountId": "5FUVPB0",
    "institutionName": "Robinhood",
    "accountName": "Margin account"
  },
  "status": "ok",
  "message": ""
}

Quickstart Guide with Link SDKs