Transfer Assets

With the Portal API’s assets/send endpoint, you can transfer both native and ERC20 tokens without the hassle of building transactions manually. Just a simple API call, and you’re set!

The Transfer Asset endpoint builds, signs, and submits a transaction to the specific blockchain. A successful 200 response indicates that the transaction was successfully received by the RPC gateway, but does not indicate that the transaction was successfully written to chain yet. The transaction will need to be picked up out of the mempool, written to chain, and finalized. This can take seconds to minutes depending on the chain.

Steps to Send Tokens

To make your first transfer, you’ll need to use the https://mpc-client.portalhq.io/v1/assets/send endpoint. This call requires you to include an authorization header with your clientApiKey and set the content type to application/json.

Here's a breakdown of the request body fields (see the full API spec here):

• share (required): This represents your part of the signing key for secure transaction processing.

• chain (required): The blockchain you are transacting on (e.g., ethereum, solana).

• to (required): The recipient address for your token transfer.

• token (required): The token you are sending (e.g., USDC, ETH).

• amount (required): The quantity of the token to send. This should be specified in the standard unit of the token.

• rpcUrl (required): The RPC URL of the blockchain network you are using (e.g., Infura for Ethereum, Alchemy for Solana).

• nonce (optional): Use this field to specify the transaction order. If you plan to submit multiple transactions in quick succession, manually set the nonce values (e.g., "0x01", "0x02", etc.) to ensure they are processed in order.

• metadataStr (required): A string used to include additional information or notes for your transaction.

Example: Sending 1 USDC on Ethereum

Let’s walk through an example. Say you want to send 1 USDC to the wallet address 0xdeadbeef on the Solana blockchain. Here’s how you’d structure your request:

curl -X POST 'https://mpc-client.portalhq.io/v1/assets/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "share": $share,
    "chain": "ethereum",
    "to": "0xdeadbeef",
    "token": "USDC",
    "amount": "1",
  }'

Understanding the Nonce Field

The nonce is an optional field but extremely useful when you want to submit multiple transactions back-to-back without waiting for chain confirmations. By specifying nonces like "0x01", "0x02", and so on, you can ensure your transactions are queued properly and get confirmed in sequence.

When the Transfer Asset endpoint is called it fetches the latest nonce for that account from the blockchain. (The nonce is incremented on chain each time a transaction is written to chain.) This means that if you send multiple requests for a single client in short order each transaction may have the same nonce value set because the blockchain hasn’t written the first transaction to chain yet. This can lead to several requests queued up at once in the mempool with the same nonce which may lead to errors from the RPC gateway as it will interpret multiple transactions with the same nonce as attempts to overwrite the transaction in the mempool.

If you’d like to submit concurrent requests for a single client, you can use the nonce parameter to submit a custom nonce with each transaction. In practice, this means tracking the nonce in your application and incrementing it with each request to the Transfer Assets endpoint.

Congratulations! 🎉

You’ve just learned how to easily send tokens using the Portal API. With just one API call, you can transfer assets securely and efficiently. Happy transacting!