V3 endpoints

These endpoints require a Client API Key as a bearer token.

Get Client Details

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

This endpoint retrieves the details of the current client, including information about associated wallets.

Headers

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

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 Assets by Chain

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

This endpoint retrieves the asset balances (native and token balances) for a specified 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.

Headers

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

Request Query Params

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

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

{}

Get NFTs by Chain

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

This endpoint retrieves the NFTs for the client for a particular chain.

Supported Chains

• Ethereum Mainnet (eip155:1)

• Ethereum Goerli (eip155:5) // @deprecated

• Ethereum Sepolia (eip155:11155111)

• Base Mainnet (eip155:8453)

• Base Sepolia (eip155:84532)

• Polygon Mainnet (eip155:137)

• Polygon Mumbai (eip155:80001)

• Polygon Amoy (eip155:80002)

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

Headers

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

Request Query Params

Name	Type	Description
chainId*	String	Must be in CAIP-2 format (e.g. "eip155:11155111").

200: Success

[
  {
    "contract": {
      "address": "0xabcdef1234567890abcdef1234567890abcdef12"
    },
    "id": {
      "tokenId": "99",
      "tokenMetadata": {
        "tokenType": "ERC721"
      }
    },
    "title": "GalacticExplorer #99",
    "description": "Galactic Explorers venture into the unknown regions of space to discover new worlds and civilizations.",
    "tokenUri": {
      "raw": "https://galacticexplorers.io/api/explorers/99",
      "gateway": "https://galacticexplorers.io/api/explorers/99"
    },
    "media": [
      {
        "raw": "https://galacticexplorers.io/explorer_images/99.png",
        "gateway": "https://galacticexplorers.io/explorer_images/99.png"
      }
    ],
    "metadata": {
      "name": "GalacticExplorer #99",
      "description": "Galactic Explorers venture into the unknown regions of space to discover new worlds and civilizations.",
      "image": "https://galacticexplorers.io/explorer_images/99.png",
      "external_url": "https://galacticexplorers.io",
      "attributes": [
        {
          "value": "Space Suit (Blue)",
          "trait_type": "Clothes"
        },
        {
          "value": "Happy Smile",
          "trait_type": "Mouth"
        },
        {
          "value": "Space",
          "trait_type": "Background"
        }
      ]
    },
    "timeLastUpdated": "2023-01-01T10:00:00.000Z",
    "contractMetadata": {
      "name": "GalacticExplorers",
      "symbol": "GEXP",
      "totalSupply": "5000",
      "tokenType": "ERC721"
    }
  },
  ...
]

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Get Transactions by Chain

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

Retrieves the client's transaction history for a specific chain.

Supported Chains

• Ethereum Mainnet (eip155:1)

• Ethereum Goerli (eip155:5) // @deprecated

• Ethereum Sepolia (eip155:11155111)

• Base Mainnet (eip155:8453)

• Base Sepolia (eip155:84532)

• Polygon Mainnet (eip155:137)

• Polygon Mumbai (eip155:80001)

• Polygon Amoy (eip155:80002)

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

Headers

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

Request Query Params

Name	Type	Description
chainId*	String	Must be in CAIP-2 format (e.g. "eip155:11155111").

200: Success

[
  {
    "blockNum": "0x57450c",
    "uniqueId": "0x3b8a06c63d02ba6826cce6188c2caa44b68dd6a36050dcfd5c085a7cba5444e3:external",
    "hash": "0x3b8a06c63d02ba6826cce6188c2caa44b68dd6a36050dcfd5c085a7cba5444e3",
    "from": "0xdfd8302f44727a6348f702ff7b594f127de3a902",
    "to": "0x8eddb4067a73061e93583897d4684b749a93f19c",
    "value": 0.01,
    "erc721TokenId": null,
    "erc1155Metadata": null,
    "tokenId": null,
    "asset": "ETH",
    "category": "external",
    "rawContract": {
      "value": "0x2386f26fc10000",
      "address": null,
      "decimal": "0x12"
    },
    "metadata": {
      "blockTimestamp": "2024-04-17T17:32:24.000Z"
    },
    "chainId": 11155111
  }
]

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Evaluate a Transaction

POST https://api.portalhq.io/api/v3/clients/me/evaluate-transaction

This endpoint evaluates a transaction by either simulating its execution or validating its authenticity (or both). The evaluation provides detailed insights into the transaction, including potential changes in asset balances, exposures, and a classification of the transaction's risk.

Supported Chains

• Ethereum Mainnet (eip155:1)

• Ethereum Sepolia (eip155:11155111)

• Optimism Mainnet (eip155:10)

• Binance Smart Chain (eip155:56)

• Polygon Mainnet (eip155:137)

• Blast Mainnet (eip155:238)

• zkSync Mainnet (eip155:324)

• zkSync Sepolia (eip155:300)

• Base Mainnet (eip155:8453)

• Base Sepolia (eip155:84532)

• Immutable zkEVM (eip155:13371)

• Arbitrum Mainnet (eip155:42161)

• Avalanche Fuji (eip155:43113)

• Avalanche Mainnet (eip155:43114)

• Linea Mainnet (eip155:59144)

• Scroll Mainnet (eip155:534352)

• Zora Mainnet (eip155:7777777)

• Degen Mainnet (eip155:666666666)

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

Headers

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

Request Query Params

Name	Type	Description
chainId*	String	Must be in CAIP-2 format (e.g. "eip155:11155111").

Request Body

Name	Type	Description
to*	String	The recipient's address.
gas	String (optional)	The gas limit provided for the transaction.
gasPrice	String (optional)	The price per unit of gas the sender is willing to pay.
maxFeePerGas	String (optional)	The maximum total fee per gas unit the sender is willing to pay.
maxPriorityFeePerGas	String (optional)	The maximum priority fee per gas unit the sender is willing to pay.
value	String (optional)	The amount of native token to send with the transaction.
data	String (optional)	The input data to send with the transaction (used for contract calls).
operationType	"validation", "simulation", or "all" Default: "all"	The operation to perform with the transaction.

200: Success

{
  "validation": {
    "status": "Success",
    "resultType": "Malicious",
    "description": "A known malicious address is involved in the transaction",
    "reason": "raw_ether_transfer",
    "classification": "known_malicious",
    "features": []
  },
  "simulation": {
    "status": "Success",
    "assetsDiffs": {
      "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14": [
        {
          "asset": {
            "type": "NATIVE",
            "chainName": "sepolia",
            "decimals": 18,
            "chainId": 11155111,
            "logoUrl": "https://cdn.blockaid.io/chain/sepolia",
            "name": "Sepolia Ether",
            "symbol": "ETH"
          },
          "in": [
            {
              "summary": "Received 0 ETH",
              "value": "0.000000000000000001",
              "rawValue": "0x1"
            }
          ],
          "out": []
        },
        {
          "asset": {
            "type": "ERC20",
            "address": "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
            "logoUrl": "https://cdn.blockaid.io/token/0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14/ethereum-sepolia",
            "decimals": 18,
            "name": "Wrapped Ether",
            "symbol": "WETH"
          },
          "in": [],
          "out": [
            {
              "summary": "Sent 0 WETH",
              "value": "0.000000000000000001",
              "rawValue": "0x1"
            }
          ]
        }
      ],
      "0x31A89E000E9029362213387FEDe26F7B543e9D1C": [
        {
          "asset": {
            "type": "NATIVE",
            "chainName": "sepolia",
            "decimals": 18,
            "chainId": 11155111,
            "logoUrl": "https://cdn.blockaid.io/chain/sepolia",
            "name": "Sepolia Ether",
            "symbol": "ETH"
          },
          "in": [],
          "out": [
            {
              "summary": "Sent 0 ETH",
              "value": "0.000000000000000001",
              "rawValue": "0x1"
            }
          ]
        },
        {
          "asset": {
            "type": "ERC20",
            "address": "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
            "logoUrl": "https://cdn.blockaid.io/token/0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14/ethereum-sepolia",
            "decimals": 18,
            "name": "Wrapped Ether",
            "symbol": "WETH"
          },
          "in": [
            {
              "summary": "Received 0 WETH",
              "value": "0.000000000000000001",
              "rawValue": "0x1"
            }
          ],
          "out": []
        }
      ]
    },
    "totalUsdDiff": {},
    "exposures": {},
    "totalUsdExposure": {},
    "addressDetails": {},
    "accountSummary": {
      "assetsDiffs": [
        {
          "asset": {
            "type": "NATIVE",
            "chainName": "sepolia",
            "decimals": 18,
            "chainId": 11155111,
            "logoUrl": "https://cdn.blockaid.io/chain/sepolia",
            "name": "Sepolia Ether",
            "symbol": "ETH"
          },
          "in": [],
          "out": [
            {
              "summary": "Sent 0 ETH",
              "value": "0.000000000000000001",
              "rawValue": "0x1"
            }
          ]
        },
        {
          "asset": {
            "type": "ERC20",
            "address": "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14",
            "logoUrl": "https://cdn.blockaid.io/token/0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14/ethereum-sepolia",
            "decimals": 18,
            "name": "Wrapped Ether",
            "symbol": "WETH"
          },
          "in": [
            {
              "summary": "Received 0 WETH",
              "value": "0.000000000000000001",
              "rawValue": "0x1"
            }
          ],
          "out": []
        }
      ],
      "exposures": [],
      "totalUsdExposure": {}
    }
  }
}

400: Bad Request Bad Request

{
  "validation": {
    "status": "Error",
    "resultType": "Error",
    "description": "",
    "reason": "",
    "classification": "",
    "features": [],
    "error": "Error message here"
  },
  "simulation": {
    "status": "Error",
    "error": "Error message here"
  }
}

401: Unauthorized Unauthorized Request

{}

Update Signing Share Pairs' Statuses

PATCH https://api.portalhq.io/api/v3/clients/me/signing-share-pairs

Updates a client's signing share pairs' statuses. Intended to be used after successfully storing the client signing share on the client's device.

Do not use this endpoint if you are using the Portal SDKs. The Portal SDKs already use this endpoint internally for your convenience.

Headers

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

Request Body

Name	Type	Description
signingSharePairIds*	String[]	An array of signing share pair IDs.
status*	"STORED_CLIENT"	The updated status of the signing share pairs.

204: Success, No Content

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Update Backup Share Pairs' Statuses

PATCH https://api.portalhq.io/api/v3/clients/me/backup-share-pairs

Updates a client's backup share pairs' statuses. Intended to be used after successfully storing the encrypted client backup share.

Do not use this endpoint if you are using the Portal SDKs. The Portal SDKs already use this endpoint internally for your convenience.

Headers

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

Request Body

Name	Type	Description
backupSharePairIds*	String[]	An array of backup share pair IDs.
status*	"STORED_CLIENT_BACKUP_SHARE_KEY" | "STORED_CLIENT_BACKUP_SHARE"	The updated status of the backup share pairs.

204: Success, No Content

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Simulate a Transaction (@deprecated)

POST https://api.portalhq.io/api/v3/clients/me/simulate-transaction

Simulates a transaction for a specific chain.

Supported Chains

• Ethereum Mainnet (eip155:1)

• Ethereum Goerli (eip155:5) // @deprecated

• Ethereum Sepolia (eip155:11155111)

• Base Mainnet (eip155:8453)

• Base Sepolia (eip155:84532)

• Polygon Mainnet (eip155:137)

• Polygon Mumbai (eip155:80001)

• Polygon Amoy (eip155:80002)

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

Headers

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

Request Query Params

Name	Type	Description
chainId*	String	Must be in CAIP-2 format (e.g. "eip155:11155111").

Request Body

Name	Type	Description
from*	String	The sender's address.
to*	String	The recipient's address.
gas	String (optional)	The gas limit provided for the transaction.
gasPrice	String (optional)	The price per unit of gas the sender is willing to pay.
maxFeePerGas	String (optional)	The maximum total fee per gas unit the sender is willing to pay.
maxPriorityFeePerGas	String (optional)	The maximum priority fee per gas unit the sender is willing to pay.
value	String (optional)	The amount of native token to send with the transaction.
data	String (optional)	The input data to send with the transaction (used for contract calls).
nonce	String (optional)	The transaction count of the sender's address, used to ensure uniqueness.

200: Success

{
  "changes": [
    {
      "amount": "0.000000000000000016",
      "assetType": "NATIVE",
      "changeType": "TRANSFER",
      "contractAddress": null,
      "decimals": 18,
      "from": "0x0282c3974e48e645d977758838a0211e5c11bd64",
      "name": "Ethereum",
      "rawAmount": "16",
      "symbol": "ETH",
      "to": "0x3fc91a3afd70395cd496c647d5a6cc9d4b2b7fad",
      "tokenId": null
    }
  ],
  "gasUsed": "0x5258"
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Get ERC20 Balances (@deprecated)

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

Retrieves the client's ERC20 balances for a specific chain.

Supported Chains

• Ethereum Mainnet (eip155:1)

• Ethereum Goerli (eip155:5) // @deprecated

• Ethereum Sepolia (eip155:11155111)

• Base Mainnet (eip155:8453)

• Base Sepolia (eip155:84532)

• Polygon Mainnet (eip155:137)

• Polygon Mumbai (eip155:80001)

• Polygon Amoy (eip155:80002)

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

Headers

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

Request Query Params

Name	Type	Description
chainId*	String	Must be in CAIP-2 format (e.g. "eip155:11155111").

200: Success

[
  {
    "contractAddress": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
    "balance": "0.000211681761928783"
  }
]

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}