Enclave MPC API Quick Start

This quick start guide will get you up and running with the Portal MPC API.

Overview

The Enclave MPC API lives at mpc-client.portalhq.io. This API allows you create, backup, and recover Portal MPC Wallets. It also allows you to sign messages and transactions for EVM and Solana chains.

Authentication

The Portal MPC API is authenticated with a Client API Key or Client Session Token via a Bearer token in the Authorization header of your requests. You can get a test Client API Key from the Portal Dashboard in the Settings -> Test Client API Keys section. Simply click the New + button.

Creating a Wallet

In order to create a new wallet, you can use /v1/generate route.

curl -X POST 'https://mpc-client.portalhq.io/v1/generate' \
    -H 'Content-type: application/json' \
    -H 'Authorization: Bearer <YOUR_TEST_CLIENT_API_KEY>' \
    -d '{}'

Response Body

The response of this request will contain the shares of a Portal Wallet - a dictionary keyed by the elliptical curve associated with the share. The value of each key will be a dictionary containing the share and id of that curve's share.

SECP256K1 represents an EVM share and ED25519 represents a Solana share.

Example Response

{
    "SECP256K1": {
        "share": "eyJjbGllbnRJZCI6IiIsImJhY2t1cFNoYXJlUGFpcklkIjoiIiwic2lnbml...",
        "id": "clu3aue3j001fs60wdecyz0qy"
    },
    "ED25519": {
        "share": "zMzMzQ4MzIyMDUwMDYwMDc1NzU2NDYzMTU1MzEyODg3MzY5MjQxNTc2lnbml...",
        "id": "clu3auej6001ds60wqhh4tzgx"
    }
}

You've just generated a Portal Wallet!

Update the Wallet Status

Now let's let the backend know that we've successfully stored the response.

We'll do this by sending a PATCH request updating the state of the signing shares of our Portal Wallet to indicate that we've successfully stored the shares.

In your production build, be sure to store the full response object in a secure location.

For this guide, just save the shares off to the side.

Pass in the id values for each of the SECP256K1 and ED25519 objects.

curl -X PATCH 'https://api.portalhq.io/api/v3/clients/me/signing-share-pairs' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_TEST_CLIENT_API_KEY>' \
    -d '{
      "status": "STORED_CLIENT",
      "signingSharePairIds": ["<YOUR_SECP256K1_SHARE_ID>", "<YOUR_ED25519_SHARE_ID>"]
    }'

This will return a 204 on success.

To see the addresses for the the different chains supported by your Portal Wallet send a request to the Get Client Details endpoint.

curl 'https://api.portalhq.io/api/v3/clients/me' \
    -H 'Authorization: Bearer <YOUR_TEST_CLIENT_API_KEY>'

Response Body

Check out the Get Client Details API reference to learn about the other values that are returned, but for this guide you can skip down to the metadata.namespaces property to see the list of addresses associated with your Portal Wallet.

Example Response

{
  ...,
  "metadata": {
    "namespaces": {
      "solana": {
        "address": "9JCnYR5kiBYGf3Csz5hLWab53n7ie8o6HaUdeVBUvPRq",
        "curve": "ED25519"
      },
      "stellar": {
        "address": "GB5ULMO2C3IWT5N5PFSBONB3WWRTNHKYCMJ53R2P4QXYRIVSVOJXBAST",
        "curve": "ED25519"
      },
      "eip155": {
        "address": "0x8257a8212a0ce84de8ffb951a42bba2a2a9ffce8",
        "curve": "SECP256K1"
      },
      "tron": {
        "address": "TMrPrVftxf1Yq8jwzrBER58LhfsiBZKhcX",
        "curve": "SECP256K1"
      }
    }
  }
}

The namespaces correlate to CAIP-2 blockchain IDs for unique chain-agnostic identification. So all EVM-based chains (Ethereum, Polygon, Optimism, Base, etc...) will use the eip155address.

Go ahead and save the eip155 address and the solana address off to the side.

If you have jq installed you can use the following command to easily parse the values.

curl 'https://api.portalhq.io/api/v3/clients/me' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TEST_CLIENT_API_KEY>' \
  | jq '.metadata.namespaces | map_values(.address) | to_entries | from_entries'

Your Portal Wallet is now ready for signing!

Submitting a Transaction

To sign and submit a transaction, we will use the /v1/assets/send route. This endpoint simplifies the process for transferring "assets" - native tokens, ERC-20 tokens, and Solana SPL tokens - across all Portal supported chains. It takes as parameters:

• share - the share string value for the specific curve you want to

• chain - the blockchain network (e.g. "ethereum", "sepolia", "solana", "solana-devnet", or a CAIP-2 chain ID like "eip155:11155111")

• token - the token contract address (for ERC20 tokens on EVM chains) or the mint address (for Solana SPL tokens). You can also use "USDC" or "USDT" for the respective tokens. For native token transfers, use the native token symbol like "ETH" or simply "NATIVE".

• to - the address you want to send to

• amount - the human readable amount you want to send (e.g. "0.1" is 0.1 USDC)

• rpcUrl - the URL to be used for outbound RPC requests such as submitting to chain (you can default to the Portal RPC URL for this endpoint)

If you want to define the transaction or message to sign use the /v1/sign route to sign any message!

If you try to transfer more funds that are available in your wallet you'll see the insufficient funds for gas * price + value message in the error response:

{
  "id": "TX_BUILD_FAILED",
  "message": "Failed to build transaction hash: populate transaction: create transaction: failed with 550000000 gas: insufficient funds for gas * price + value: address 0x8257a8212A0Ce84De8fFb951a42BbA2A2a9fFCE8 have 610317254949000 want 1000000000000000000",
  "code": 308
}

Make sure you have enough Sepolia ETH and that you supplied the correct chain.

If the JSON request body is malformed you'll see the Can't parse the requests body message in the error response.

{
  "id":"BAD_REQUEST",
  "message":"Can\'t parse the request body",
  "code":201
}

Make sure your request body is properly formatted.

Submitting an EVM Transaction

Let's use the Ethereum Sepolia testnet to send our first EVM transaction. Visit sepoliafaucet.io, or another testnet faucet, to get some testnet Sepolia ETH.

Once you've successfully collected some Sepolia ETH, you'll be able to view your balance on the blockchain explorer, in this case https://sepolia.etherscan.io/. Add your eip155 address to see your Sepolia ETH balance.

We are now ready to send an EVM transaction!

Example Request

• share - use the string value associated with the share property of the SECP256K1 object returned in the generate response

• chain - set the value to sepolia which is a shorthand for Ethereums Sepolia testnet

• token - we'll use ETH but we also could use NATIVE to indicate we want to transfer the native ETH token on Sepolia

• to - we've added a test address to transfer funds to

• amount - we should have 0.01 Sepolia ETH, so we'll transfer 0.001 of it

• rpcUrl - the default Portal RPC URL

curl -X POST 'https://mpc-client.portalhq.io/v1/assets/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TEST_CLIENT_API_KEY>' \
  -d '{
    "share": "<YOUR_SECP256K1_SHARE>",
    "chain": "sepolia",
    "token": "ETH",
    "to": "0xcae0d97d201ad54275b6e8a6b547c7611ad47963",
    "amount": "0.0001",
    "rpcUrl": "https://api.portalhq.io/rpc/v1/eip155/11155111"
  }'

Response

Example Response

On a successful submission you will receive a 200 and a similar response body:

{
  "transactionHash": "0x2ca7d87c9cb56965224faeeba22f15216ab480581db6902975cb0c494b58edf2",
  "metadata": {
    "amount": ".0001",
    "rawAmount": "100000000000000",
    "tokenDecimals": 18,
    "tokenSymbol": "ETH"
  }
}

You can search the transactionHash on sepolia.etherscan.io to see the details on the blockchain explorer.

You've just signed and submitted your first EVM transaction with a Portal Wallet!

Submitting a Solana Transaction

Let's use the Solana Devnet to send our first Solana transaction. Visit faucet.solana.com, or another faucet, to get some Solana Devnet SOL tokens.

Once you've successfully collected some Devnet SOL, you'll be able to view your balance on the blockchain explorer, in this case solscan.io/?cluster=devnet. Add your solana address to see your Devnet SOL balance.

We are now ready to send a Solana transaction!

Example Request

• share - use the string value associated with the share property of the ED25519 object returned in the generate response

• chain - set the value to solana-devnet which is a shorthand for Solana Devnet

• token - we'll use NATIVE to indicate we want to transfer the native SOL token on Solana Devnet

• to - we've added a test address to transfer funds to

• amount - we'll transfer 0.001 of our Devnet SOL

curl -X POST 'https://mpc-client.portalhq.io/v1/assets/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TEST_CLIENT_API_KEY>' \
  -d '{
    "share": "<YOUR_ED25519_SHARE>",
    "chain": "solana-devnet",
    "token": "NATIVE",
    "to": "75ZfLXXsSpycDvHTQuHnGQuYgd2ihb6Bu4viiCCQ7P4H",
    "amount": "0.0001"
  }'

Response

Example Response

On a successful submission you will receive a 200 and a similar response body:

{
  "transactionHash": "4TDjz6rnYhKRMmdBBZNBxfEP9AVbd5dDt9m3aEQTJm3cioDFqtnDo7ZcZbs5xQc3vwCf4eAg9vxi1kD46th4wKxq",
  "metadata": {
    "amount": "0.0001",
    "lastValidBlockHeight": "336343025",
    "rawAmount": "100000",
    "tokenDecimals": 9,
    "tokenSymbol": "SOL"
  }
}

You can search the transactionHash on solscan.io/?cluster=devnet to see the details on the blockchain explorer.

You've just signed and submitted your first Solana transaction with a Portal Wallet!