V3 endpoints

These endpoints require a Portal API Key (aka "Custodian API Key") as a bearer token.

Before going live with real users, always ensure that you create clients using a Portal API Key from your Portal's Production environment. Read more here on going live with real users.

Create a new client

POST https://api.portalhq.io/api/v3/custodians/me/clients

Registers a new client and returns a client API key, client session token, and whether they are AA enabled.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

Request Body

Name	Type	Description
isAccountAbstracted	Boolean (optional)	The client will use ERC-4337 Account Abstraction (AA).

Example Response

201: Created Success

{
  "id": "string",
  "clientApiKey": "string",
  "clientSessionToken": "string",
  "isAccountAbstracted": boolean
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Fetches a single client

GET https://api.portalhq.io/api/v3/custodians/me/clients/[clientId]

Fetches the specified client for the authorized custodian.

Path Parameters

Name	Type	Description
clientId*	String	The ID of the client.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

Example Response

200: OK Success

{
  "createdAt": "2024-04-16T21:15:06.443Z",
  "custodian": {
    "id": "custodianId",
    "name": "Custodian Name"
  },
  "ejectedAt": null,
  "environment": {
    "id": "environmentId",
    "name": "Development"
  },
  "id": "clientId",
  "isAccountAbstracted": false,
  "metadata": {
    "namespaces": {
      "eip155": {
        "address": "0x6e818d8f9b6c53c59a2d957d36c2146e28906195",
        "curve": "SECP256K1"
      }
    }
  },
  "wallets": [
    {
      "createdAt": "2024-04-16T21:15:45.144Z",
      "curve": "SECP256K1",
      "id": "wallet1Id",
      "backupSharePairs": [
        {
          "backupMethod": "PASSWORD",
          "createdAt": "2024-04-16T21:16:48.723Z",
          "id": "backupSharePairId1",
          "status": "completed"
        },
        {
          "backupMethod": "GDRIVE",
          "createdAt": "2024-04-16T21:17:02.074Z",
          "id": "backupSharePairId2",
          "status": "incomplete"
        },
        {
          "backupMethod": "ICLOUD",
          "createdAt": "2024-04-16T21:18:06.996Z",
          "id": "backupSharePairId3",
          "status": "incomplete"
        }
      ],
      "signingSharePairs": [
        {
          "createdAt": "2024-04-16T21:15:45.151Z",
          "id": "signingSharePairId1",
          "status": "completed"
        }
      ],
      "publicKey": "stringifiedJSON"
    }
  ]
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Get Client's Assets by Chain

GET https://api.portalhq.io/api/v3/custodians/me/clients/:clientId/chains/:chain/assets

This endpoint retrieves the asset balances (native and token balances) for a specified client and blockchain. It provides detailed information on the native balance and token balances held by a given address on the specified chain.

Supported Chains

You can use either the full chain identifier or the shortcut for popular chains.

• Ethereum Mainnet (eip155:1 or ethereum)

• Ethereum Sepolia (eip155:11155111 or sepolia)

• Solana Mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp or solana)

• Solana Devnet (solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 or solana-devnet)

• Base Mainnet (eip155:8453 or base)

• Base Sepolia (eip155:84531 or base-sepolia)

• Polygon Mainnet (eip155:137 or polygon)

• Polygon Mumbai (eip155:80001 or polygon-mumbai)

• Optimism Mainnet (eip155:10)

• Cronos (eip155:25)

• Binance Smart Chain (eip155:56)

• Binance Smart Chain Testnet (eip155:97)

• Gnosis (eip155:100)

• Fantom (eip155:250)

• Moonbeam (eip155:1284)

• Moonriver (eip155:1285)

• Moonbase (eip155:1287)

• Gnosis Testnet (eip155:10200)

• Holesky (eip155:17000)

• Arbitrum Mainnet (eip155:42161)

• Avalanche Mainnet (eip155:43114)

• Linea Mainnet (eip155:59140)

• Linea Sepolia (eip155:59141)

• Chiliz Testnet (eip155:88882)

• Chiliz (eip155:88888)

• Optimism Sepolia (eip155:11155420)

• Palm (eip155:11297108109)

When using CAIP-2 chain formats in the URL (e.g. eip155:11155111), ensure the URL is URI encoded to accommodate the ":" character.

Path Parameters

Name	Type	Description
clientId*	String	The ID of the client.
chainId*	String	Must be in CAIP-2 format or chain identifier shortcut (e.g. eip155:11155111 or sepolia).

Headers

Name	Type	Description
Authorization*	String	Bearer <Client API Key>
Content-Type*	String	application/json

Example Response

200: Success

{
  "nativeBalance": {
    "balance": "1",
    "decimals": 9,
    "name": "Solana",
    "rawBalance": "1000000000",
    "symbol": "SOL",
    "metadata": {}
  },
  "tokenBalances": [
    {
      "balance": "1000",
      "decimals": 6,
      "name": "USD Coin Dev",
      "rawBalance": "1000000000",
      "symbol": "USDC-Dev",
      "metadata": {
        "associatedTokenAddress": "JA6UyBXbukQB1qZScqBxwXcW12dGAN1HUF55qrK7R6sx",
        "mint": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr"
      }
    }
  ]
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Fetches a list of clients

GET https://api.portalhq.io/api/v3/custodians/me/clients

Fetches all clients for the authorized custodian.

Query Parameters

Name	Type	Description
cursor	String (optional)	The ID of the last client in the list. Used for cursor-based pagination.
take	Number (optional)	The number of records to retrieve. Maximum is 100. Default is 100.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

Example Response

200: OK Success

```json
{
  "results": [
    {
      "createdAt": "2024-04-16T21:15:06.443Z",
      "custodian": {
        "id": "custodianId",
        "name": "Custodian Name"
      },
      "ejectedAt": null,
      "environment": {
        "id": "environmentId",
        "name": "Development"
      },
      "id": "clientId",
      "isAccountAbstracted": false,
      "metadata": {
        "namespaces": {
          "eip155": {
            "address": "0x6e818d8f9b6c53c59a2d957d36c2146e28906195",
            "curve": "SECP256K1"
          }
        }
      },
      "wallets": [
        {
          "createdAt": "2024-04-16T21:15:45.144Z",
          "curve": "SECP256K1",
          "id": "wallet1Id",
          "backupSharePairs": [
            {
              "backupMethod": "PASSWORD",
              "createdAt": "2024-04-16T21:16:48.723Z",
              "id": "backupSharePairId1",
              "status": "completed"
            },
            {
              "backupMethod": "GDRIVE",
              "createdAt": "2024-04-16T21:17:02.074Z",
              "id": "backupSharePairId2",
              "status": "incomplete"
            },
            {
              "backupMethod": "ICLOUD",
              "createdAt": "2024-04-16T21:18:06.996Z",
              "id": "backupSharePairId3",
              "status": "incomplete"
            }
          ],
          "signingSharePairs": [
            {
              "createdAt": "2024-04-16T21:15:45.151Z",
              "id": "signingSharePairId1",
              "status": "completed"
            }
          ],
          "publicKey": "stringifiedJSON"
        }
      ]
    },
    ...
  ],
  "metadata": {
    "cursor": "nextCursorToUse",
    "take": 100,
    "total": 1000
  }
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Refresh Client Session Token (CST)

POST https://api.portalhq.io/api/v3/custodians/me/clients/[clientId]/sessions

Refreshes a Client Session Token for a client.

Path Parameters

Name	Type	Description
clientId*	String	The ID of a client.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

Example Response

200: OK Success

{
  "id": "string",
  "clientSessionToken": "string",
  "isAccountAbstracted": boolean
}

400: Bad Request Bad Request

{
  "error": "string"
}

401: Unauthorized Unauthorized Request

{
  "error": "string"
}

Generate Client Web One-Time Password (OTP)

POST https://api.portalhq.io/api/v1/custodians/clients/[clientId]/web-otp

Generate a one-time password for a client.

Path Parameters

Name	Type	Description
clientId*	String	The ID of a client.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

Example Response

200: OK Success

{
  "id": "string"
  "otp": "string"
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized

{}