Sign Ethereum transactions

So far you have been able to create a Portal client and create their MPC wallets. Now, lets sign a transaction and send someone some MON tokens over Monad Testnet.

Steps

In order to send your first transaction, you’ll first need to fund your wallet. You can get some test MON tokens by using the Client API Fund Wallet endpoint.

curl --request POST \
  --url https://api.portalhq.io/api/v3/clients/me/fund \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
	"chainId": "eip155:10143",
	"token": "NATIVE",
	"amount": "0.01"
}'

Next, we’ll need to format a transaction object.

Here is the example transaction:

const transaction = {
  "value": "0x01",
  "from": "YOUR_ETH_ADDRESS",
  "to": "RECIPIENT_ADDRESS",
  "data": ""
};

Now that we some testnet ETH, let’s send a transaction! We will send our test funds to a Portal test wallet using a single API request to https://mpc-client.portalhq.io/v1/sign .
1. You can learn more about Ethereum transactions here, but for this example you only need to know about a few fields:
  1. method: this defines which Ethereum RPC signer method we want to use.
  2. params : these are the parameters of your transaction.
    - value : this is the amount of MON measured in wei and hex encoded.
    - from: this is the address of the sender - your wallet in this case.
    - to: this is the address you’re sending to - our test wallet in this case.
    - data: this is used for interacting with smart contracts - we can ignore it.

In the example below we are using the eth_sendTransaction Ethereum RPC method to instruct the Portal API to both sign and submit a transaction to the blockchain.

curl -X POST 'https://mpc-client.portalhq.io/v1/sign' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "share": $share,
    "method": "eth_sendTransaction",
    "params": {"value": "0x01","from": "YOUR_ETH_ADDRESS","to": "RECIPIENT_ADDRESS","data": ""},
    "rpcUrl": "YOUR_RPC_URL",
    "chainId": "eip155:10143"
  }'

If your wallet is not funded, you will receive a RPC error on this step.

Congrats! 🎉 You have successfully created a wallet and signed a transaction!

Sign a user operation without submitting it

If your client uses Account Abstraction, eth_sendTransaction builds, signs and submits an ERC-4337 user operation for you in one call. Use eth_signUserOperation when you want Portal to build and sign the user operation but submit it to a bundler yourself. You do not build the user operation. You send a transaction, and Portal returns the signed user operation made from it. To batch several calls into one user operation, or to have Portal submit it for you, use Build, sign and broadcast a user operation instead.

Steps

Call /v1/sign with method set to eth_signUserOperation. params is the same transaction you would pass to eth_sendTransaction, as a JSON object or a JSON-encoded string:

Field	Required	Description
`to`	Yes	The address the smart account calls.
`value`	No	Native value in wei, hex encoded. The smart account must hold it, or the call fails with `TX_BUILD_FAILED`.
`data`	No	Calldata for the call to `to`.
`nonce`	No	ERC-4337 nonce, hex encoded. Omit it to use the smart account’s next nonce. See Concurrent transactions.

curl -X POST 'https://mpc-client.portalhq.io/v1/sign' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "share": "YOUR_SECP256K1_SHARE",
    "method": "eth_signUserOperation",
    "params": {"from": "YOUR_ETH_ADDRESS", "to": "RECIPIENT_ADDRESS", "value": "0x0", "data": "0x"},
    "rpcUrl": "https://api.portalhq.io/rpc/v1/eip155/11155111",
    "chainId": "eip155:11155111"
  }'

The response data is the signed user operation, encoded as hex of its JSON:

{
  "data": "7b2273656e646572223a22307846383665336641653834343365343439346136383966634464344338…"
}

Decode it back to JSON:

const { data } = await response.json()
const userOperation = JSON.parse(Buffer.from(data, 'hex').toString('utf8'))

The decoded user operation looks like this:

{
  "sender": "0xF86e3fAe8443e4494a689fcDd4C8e6C76c1b2C96",
  "nonce": "0x0",
  "initCode": "0x5de4839a…",
  "callData": "0x51945447…",
  "callGasLimit": "0x238c",
  "verificationGasLimit": "0x659a5",
  "preVerificationGas": "0xd564",
  "maxFeePerGas": "0x59e709d8",
  "maxPriorityFeePerGas": "0x16addf3",
  "paymasterAndData": "0x66666666…",
  "signature": "0x000000003e42da7c…"
}

Submit the decoded user operation, unchanged, to an ERC-4337 bundler (Portal’s RPC endpoint does not accept eth_sendUserOperation for these operations yet) with eth_sendUserOperation and the EntryPoint v0.6 address 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789. For example, with Pimlico:

# DATA is the hex `data` from step 2
USER_OPERATION=$(echo "$DATA" | xxd -r -p)

curl -X POST 'https://api.pimlico.io/v2/11155111/rpc?apikey=YOUR_PIMLICO_API_KEY' \
  -H 'Content-Type: application/json' \
  -d "$(jq -n --argjson op "$USER_OPERATION" \
    '{jsonrpc: "2.0", id: 1, method: "eth_sendUserOperation", params: [$op, "0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789"]}')"

The bundler returns the user operation hash:

{ "jsonrpc": "2.0", "id": 1, "result": "0xe6cebaa12cad96257938545f2a1709d9a294ef5167933c1329beefc7cece622c" }

Poll the bundler with eth_getUserOperationReceipt and that hash until it returns a result. success tells you whether the call inside the user operation succeeded, and receipt.transactionHash is the on-chain transaction:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "userOpHash": "0xe6cebaa12cad96257938545f2a1709d9a294ef5167933c1329beefc7cece622c",
    "sender": "0xF86e3fAe8443e4494a689fcDd4C8e6C76c1b2C96",
    "nonce": "0x2",
    "actualGasCost": "0x5d1ff0c92fad",
    "success": true,
    "receipt": {
      "transactionHash": "0x47a5e5697d423d162a61d67a97f218a35afc8482d8f0fe8148394673a07756ea",
      "blockNumber": "0xb3c375",
      "status": "0x1"
    }
  }
}

Things to know

Every field is covered by the signature, so any change, including gas fees, invalidates it. Call eth_signUserOperation again instead of editing the result. A bundler whose minimum fees are higher than the ones Portal priced will reject the user operation.
signature already carries the 4 leading zero bytes the smart account expects.
initCode is set until the smart account is deployed. The first user operation you submit deploys it.
Gas is sponsored by default when your environment has gas sponsorship configured for the chain. To opt out, pass "sponsorGas": false at the top level of the request body (next to method, not inside params); paymasterAndData then comes back empty and the smart account pays for gas.
When the smart account pays its own gas, EntryPoint v0.6 takes the maximum possible gas cost up front and refunds the unused part to the account’s EntryPoint deposit (balanceOf(sender) on the EntryPoint), not its native balance. The deposit is used toward the next user operation’s gas.
If sponsorship is not available for an operation, the call still succeeds and paymasterAndData comes back empty. Check it before submitting: with no paymaster, the smart account must hold enough native token to pay for gas, or the bundler rejects the operation with AA21 didn't pay prefund.
Paymaster data on a sponsored user operation is only valid for a short time (about 10 minutes), so submit it soon after signing.
eth_signUserOperation only works for Account Abstraction clients. Other clients get a 400 with METHOD_UNSUPPORTED.

Build, sign and broadcast a user operation

Use this flow when you want to batch several calls into one ERC-4337 user operation, or to see the user operation and its gas estimate before signing it. To control every field of the user operation yourself, see Sign a user operation you built. Portal builds the user operation, you sign its hash with the Enclave MPC API, and Portal submits it to the bundler. You do not need a bundler of your own. It works for Account Abstraction clients only.

Steps

Build the user operation with the Client API build user operation endpoint. Each entry in calls is one call the smart account makes, in order:

Field	Required	Description
`to`	Yes	The address to call.
`value`	No	Native value in wei, as a decimal or hex string. Defaults to `0`.
`data`	No	Calldata for the call. Defaults to `0x`.

curl -X POST 'https://api.portalhq.io/api/v3/clients/me/chains/eip155:11155111/assets/send/build-user-operation' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "calls": [
      {"to": "FIRST_ADDRESS", "value": "0"},
      {"to": "SECOND_ADDRESS", "value": "0", "data": "0x"}
    ]
  }'

The response has the user operation as a JSON string, the hash to sign, and a gas estimate. estimatedGasCostWei is the most the user operation can cost when the smart account pays for its own gas:

{
  "data": {
    "userOperation": "{\"sender\":\"0xF86e3fAe8443e4494a689fcDd4C8e6C76c1b2C96\",\"nonce\":\"0x5\",\"initCode\":\"0x\",\"callData\":\"0x34fcd5be…\",\"paymasterAndData\":\"0x\",\"signature\":\"0x00000000ffff…\",\"maxFeePerGas\":\"0x58556415\",\"maxPriorityFeePerGas\":\"0x15d0ea4\",\"callGasLimit\":\"0x3f9b\",\"verificationGasLimit\":\"0x13d75\",\"preVerificationGas\":\"0xc808\"}",
    "userOpHash": "0xba1f6f1fe76b7a39d660bd02f54a3de5eae99ab413a95246e394c06786003847"
  },
  "metadata": {
    "chainId": "eip155:11155111",
    "totalGas": "148760",
    "maxFeePerGas": "1481991189",
    "estimatedGasCostWei": "220461009275640"
  }
}

Sign userOpHash with the raw signing endpoint, without the 0x prefix:

curl -X POST 'https://mpc-client.portalhq.io/v1/raw/sign/SECP256K1' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "share": "YOUR_SECP256K1_SHARE",
    "params": "ba1f6f1fe76b7a39d660bd02f54a3de5eae99ab413a95246e394c06786003847"
  }'

The response data is the signature.

Broadcast the user operation with the Client API broadcast user operation endpoint. Pass userOperation exactly as the build step returned it, and the signature exactly as the raw signing endpoint returned it. Portal formats the signature for the smart account and submits the user operation to the bundler:

curl -X POST 'https://api.portalhq.io/api/v3/clients/me/chains/eip155:11155111/assets/send/broadcast-user-operation' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "userOperation": "USER_OPERATION_FROM_STEP_1",
    "signature": "SIGNATURE_FROM_STEP_2"
  }'

{
  "data": {
    "userOpHash": "0xf82a8a15e20eec1c8c3057fc56df67d7da3dc668e2b0dd3c7380ddc9175867d1"
  },
  "metadata": {
    "chainId": "eip155:11155111"
  }
}

Look up the user operation hash with get transaction (GET /api/v3/clients/me/chains/{chain}/transactions/{hash}). The on-chain transaction hash appears once a bundler includes the user operation, usually within a few seconds; until then the lookup returns 404.

Things to know

Sign and broadcast soon after building. The user operation carries the gas prices and nonce from the moment it was built, and a sponsored one carries paymaster data that expires after a few minutes.
The build step runs your environment’s transaction policies on every call, and returns 403 with policyViolation when one blocks it.
Gas is sponsored when your environment has gas sponsorship configured for the chain. If paymasterAndData in the built user operation is 0x, the smart account pays for gas and needs enough native token to cover estimatedGasCostWei.
Clients without Account Abstraction get a 400: Account Abstraction is not enabled, contact support to enable it.

Sign a user operation you built

Use this flow when you build the user operation yourself, for example to use your own paymaster, gas settings or calldata encoding. Portal only signs its hash. You can then submit it through Portal or to your own bundler. The user operation has to match the smart account Portal created for the client:

Field	Value
`sender`	The client’s smart account: `metadata.smartContractAddress` from the account type endpoint.
EntryPoint	v0.6, `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789`.
`callData`	A ZeroDev Kernel v2 call: `execute(address to, uint256 value, bytes data, uint8 operation)`, with `operation` `0` for a call.
`nonce`	`getNonce(sender, 0)` on the EntryPoint, or a 2D nonce for parallel sends.
`initCode`	`0x` once the smart account is deployed. The first user operation sent with `eth_sendTransaction` or the flows above deploys it.
Gas fields	From your bundler’s `eth_estimateUserOperationGas`, with a placeholder signature of the same shape as a real one.

Steps

Compute the EntryPoint v0.6 user operation hash, for example with viem:

import { getUserOperationHash } from 'viem/account-abstraction'

const userOpHash = getUserOperationHash({
  chainId: 11155111,
  entryPointAddress: '0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789',
  entryPointVersion: '0.6',
  userOperation, // every field except the final signature
})

Portal smart accounts use EntryPoint v0.6 at 0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789, the same address on every chain where Portal supports Account Abstraction.

Sign userOpHash with the raw signing endpoint, without the 0x prefix:

curl -X POST 'https://mpc-client.portalhq.io/v1/raw/sign/SECP256K1' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <clientApiKey>' \
  -d '{
    "share": "YOUR_SECP256K1_SHARE",
    "params": "USER_OP_HASH_WITHOUT_0x"
  }'

The response data is a 65-byte signature: r, s, then a recovery id of 00 or 01.

Submit the user operation one of two ways:
- Through Portal: call broadcast user operation with your user operation as userOperation and the signature exactly as the raw signing endpoint returned it. Portal formats the signature for the smart account and submits it.
- To your own bundler: format the signature for the Kernel smart account first, then call eth_sendUserOperation:

const raw = data.replace(/^0x/, '')
let v = parseInt(raw.slice(128, 130), 16)
if (v < 27) v += 27 // recovery id 0/1 -> 27/28
userOperation.signature = '0x00000000' + raw.slice(0, 128) + v.toString(16).padStart(2, '0')

The 0x00000000 prefix selects the Kernel smart account’s default validator. A signature without it, or with a v of 00/01, fails validation at the bundler.

Confirm inclusion with get transaction for the user operation hash, or with your bundler’s eth_getUserOperationReceipt.

Getting Started

SDKs

APIs

Integrations

Resources

Sign Ethereum transactions

Steps

Sign a user operation without submitting it

Steps

Things to know

Build, sign and broadcast a user operation

Steps

Things to know

Sign a user operation you built

Steps

​Steps

​Sign a user operation without submitting it

​Steps

​Things to know

​Build, sign and broadcast a user operation

​Steps

​Things to know

​Sign a user operation you built

​Steps

Steps

Sign a user operation without submitting it

Steps

Things to know

Build, sign and broadcast a user operation

Steps

Things to know

Sign a user operation you built

Steps