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 |
Content-Type* | String | application/json |
Request Body
Name | Type | Description |
---|---|---|
isAccountAbstracted | Boolean (optional) | The client will use ERC-4337 Account Abstraction (AA). |
Example Response
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 |
Content-Type* | String | application/json |
Example Response
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.
This endpoint is powered in partnership with Moralis.
Supported Chains
You can use either the full chain identifier or the shortcut for popular chains.
Ethereum Mainnet (
eip155:1
orethereum
)Ethereum Sepolia (
eip155:11155111
orsepolia
)Solana Mainnet (
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
orsolana
)Solana Devnet (
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
orsolana-devnet
)Base Mainnet (
eip155:8453
orbase
)Base Sepolia (
eip155:84532
orbase-sepolia
)Polygon Mainnet (
eip155:137
orpolygon
)Polygon Amoy (
eip155:80002
orpolygon-amoy
)Optimism Mainnet (
eip155:10
)Binance Smart Chain (
eip155:56
)Binance Smart Chain Testnet (
eip155:97
)Fantom (
eip155:250
)Moonbeam (
eip155:1284
)Arbitrum Mainnet (
eip155:42161
)Avalanche Mainnet (
eip155:43114
)Linea Mainnet (
eip155:59140
)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. |
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer |
Content-Type* | String | application/json |
Example Response
Build a "Send Asset" Transaction
POST
https://api.portalhq.io/api/v3/custodians/me/clients/:clientId/chains/:chain/assets/send/build-transaction
Creates an unsigned transaction for transferring assets to another address on a specific chain. You can then use this unsigned transaction to sign and submit the transaction.
Supported Chains
You can use any of the following friendly chain names for the
chain
path param (or alternatively you can use the CAIP-2chainId
):ethereum
(eip155:1
)sepolia
(eip155:11155111
)base
(eip155:8453
)base-sepolia
(eip155:84531
)polygon
(eip155:137
)polygon-mumbai
(eip155:80001
)solana
(solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
)solana-devnet
(solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
)
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 |
Content-Type* | String | application/json |
Request Path Params
Name | Type | Description |
---|---|---|
clientId* | String | The ID of the client. |
chain* | String | Must be one of the chains in "Supported Chains". |
Request Body
Name | Type | Description |
---|---|---|
to* | String | The recipient's address. |
token* | String | The token symbol (e.g., "USDC") or contract address or mint address (for Solana). |
amount* | String | The amount to transfer (as a string, in the token's primary denomination). For example, "0.01" is 1 cent of USDC. |
Example Request
Example Response
The response includes the unsigned transaction details and metadata. The structure of the response differs depending on whether the chain is Solana or an EIP-155 chain (e.g., Ethereum, Polygon, Base).
Notes
The
token
field can accept either a token symbol (e.g. "USDC" or "USDT") or a contract address (for EIP-155 tokens) or a mint address (for Solana tokens).The
amount
should be provided in the token's primary denomination (e.g. whole USDC, not micro-USDC).This endpoint creates an unsigned transaction. The client is responsible for signing the transaction before broadcasting it to the network.
The response structure differs between Solana and EIP-155 chains. Make sure to handle both response types in your implementation.
Format Raw Wallet Alerts
POST
https://api.portalhq.io/api/v3/custodians/me/alerts/format
This endpoint formats a raw webhook request body for wallet events, which may include one or many transactions at once.
This endpoint is powered in partnership with Moralis.
Supported Chains
You can use either the full chain identifier or the shortcut for popular chains.
Ethereum Mainnet (
eip155:1
orethereum
)Ethereum Sepolia (
eip155:11155111
orsepolia
)Solana Mainnet (
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
orsolana
)Solana Devnet (
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
orsolana-devnet
)Base Mainnet (
eip155:8453
orbase
)Base Sepolia (
eip155:84531
orbase-sepolia
)Polygon Mainnet (
eip155:137
orpolygon
)Polygon Mumbai (
eip155:80001
orpolygon-mumbai
)
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer |
Content-Type* | String | application/json |
Request Body
Name | Type | Description |
---|---|---|
chain* |
| The chain the raw webhook event is from. |
rawAlert* | String | The stringified raw webhook event. |
Example Response
Resend Wallet Alert by Block Number
POST
https://api.portalhq.io/api/v3/custodians/me/alerts/retry-by-block-number
This endpoint attempts to resend a wallet event scoped by a block number in the scenario you need to replay a transaction.
This endpoint is powered in partnership with Moralis.
Supported Chains
EVM chains.
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer |
Content-Type* | String | application/json |
Request Body
Name | Type | Description |
---|---|---|
chainReferenceId* | String | The EVM chain reference ID. (e.g. |
blockNumber* | Number | The block number of the transaction(s) you want to resend. |
streamId* | String | The ID of the stream that Portal configured for you. (Reach out to our team to get this.) |
Example Response
No content
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
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 |
Content-Type* | String | application/json |
Example Response
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
Format Raw Wallet Alert (@deprecated, instead use this)
POST
https://api.portalhq.io/api/v3/custodians/me/alerts/wallets/format
This endpoint formats a raw webhook request body for wallet events.
This endpoint is powered in partnership with Moralis.
Supported Chains
You can use either the full chain identifier or the shortcut for popular chains.
Ethereum Mainnet (
eip155:1
orethereum
)Ethereum Sepolia (
eip155:11155111
orsepolia
)Solana Mainnet (
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
orsolana
)Solana Devnet (
solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1
orsolana-devnet
)Base Mainnet (
eip155:8453
orbase
)Base Sepolia (
eip155:84531
orbase-sepolia
)Polygon Mainnet (
eip155:137
orpolygon
)Polygon Mumbai (
eip155:80001
orpolygon-mumbai
)
Headers
Name | Type | Description |
---|---|---|
Authorization* | String | Bearer |
Content-Type* | String | application/json |
Request Body
Name | Type | Description |
---|---|---|
chain* |
| The chain the raw webhook event is from. |
rawAlert* | String | The stringified raw webhook event. |
Example Response
Last updated