Onchain Wallet

The Prime Onchain Wallet REST API provides programmatic access to the Onchain Wallet, enabling workflow automation for tasks such as sending, receiving, and onchain trading. This enhances operational efficiency, minimizes manual intervention, and ensures secure, seamless transactions across supported blockchains.

Creating an Onchain Wallet

An onchain wallet can be created using the same Create Wallet endpoint detailed in the Wallets concepts page. See below for examples on how to process this creation:

WalletsService walletsService = PrimeServiceFactory.createWalletsService(client);

CreateWalletRequest request = new CreateWalletRequest.Builder()
.portfolioId("PORTFOLIO_ID_HERE")
.type(WalletType.ONCHAIN)
.name("ONCHAIN_WALLET_EXAMPLE")
.build();

CreateWalletResponse response = walletsService.createWallet(request);

To learn more about this SDK, please visit the Prime Java SDK.

var request = new CreateWalletRequest("PORTFOLIO_ID_HERE")
{
    Type = WalletType.ONCHAIN,
    Name = "ONCHAIN_WALLET_EXAMPLE",
}

var response = walletsService.CreateWallet(request);

To learn more about this SDK, please visit the Prime .NET SDK.

walletsService := users.NewWalletsService(client)

request := &users.CreateWalletRequest{
PortfolioId: "PORTFOLIO_ID_HERE",
Type: model.WalletTypeOnchain,
Name: "ONCHAIN_WALLET_EXAMPLE",
}

response, err := walletsService.CreateWallet(context.Background(), request)

To learn more about this SDK, please visit the Prime Go SDK.

from prime_sdk.credentials import Credentials
from prime_sdk.client import Client
from prime_sdk.services.wallets import WalletsService, CreateWalletRequest, WalletType

credentials = Credentials.from_env("PRIME_CREDENTIALS")
client = Client(credentials)
wallets_service = WalletsService(client)

request = CreateWalletRequest(
portfolio_id="PORTFOLIO_ID_HERE",
name="ONCHAIN_WALLET_EXAMPLE",
wallet_type=WalletType.ONCHAIN.value,
)

response = wallets_service.create_wallet(request)

To learn more about this SDK, please visit the Prime Python SDK.

primectl create-wallet --help

const walletsService = new WalletsService(client);

walletsService.getWalletDepositInstructions({
portfolioId: 'PORTFOLIO_ID_HERE',
type: WalletType.ONCHAIN,
name: "ONCHAIN_WALLET_EXAMPLE",
}).then(async (response) => {
console.log('Wallet: ', response);
})

To learn more about this SDK, please visit the Prime TS SDK.

Receiving funds into Prime Onchain Wallet

This functionality works identically to deriving a deposit address for any other Prime wallet. See Deposits for more information.

Address groups

Prime Onchain Wallet utilizes address groups, which are collections of addresses organized for specific purposes, such as grouping addresses associated with a particular Uniswap pool. To list the available Onchain Address Groups, use the List Onchain Address Groups endpoint. An example request is shown below:

OnchainAddressBookService onchainAddressBookService = PrimeServiceFactory.createOnchainAddressBookService(client);

ListOnchainAddressBookRequest request = new ListOnchainAddressBookRequest.Builder()
    .portfolioId("PORTFOLIO_ID_HERE")
    .build();

ListOnchainAddressBookResponse response = onchainAddressBookService.listOnchainAddressBook(request);

To learn more about this SDK, please visit the Prime Java SDK.

var onchainAddressBookService = new OnchainAddressBookService(client);

var request = new ListOnchainAddressBookRequest("PORTFOLIO_ID_HERE");
var response = onchainAddressBookService.ListOnchainAddressBook(request);

To learn more about this SDK, please visit the Prime .NET SDK.

onchainAddressBookService := onchainaddressbook.NewOnchainAddressBookService(client)

request := &onchainaddressbook.ListOnchainAddressBookRequest{
    PortfolioId: "PORTFOLIO_ID_HERE",
}

response, err := onchainAddressBookService.ListOnchainAddressBook(context.Background(), request)

To learn more about this SDK, please visit the Prime Go SDK.

from prime_sdk.credentials import Credentials
from prime_sdk.client import Client
from prime_sdk.services.onchain_address_book import OnchainAddressBookService, ListOnchainAddressBookRequest

credentials = Credentials.from_env("PRIME_CREDENTIALS")
client = Client(credentials)
onchain_address_book_service = OnchainAddressBookService(client)

request = ListOnchainAddressGroupsRequest(
    portfolio_id="PORTFOLIO_ID_HERE"
)

response = onchain_address_book_service.list_onchain_address_groups(request)

To learn more about this SDK, please visit the Prime Python SDK.

const onchainAddressBookService = new OnchainAddressBookService(client);

onchainAddressBookService.listOnchainAddressBook({
    portfolioId: 'PORTFOLIO_ID_HERE'
}).then(async (response) => {
    console.log('Onchain Address Groups: ', response);
})

To learn more about this SDK, please visit the Prime TS SDK.

primectl list-onchain-address-groups --help

To learn more about this CLI, please visit the Prime CLI.

Creating an onchain transaction

Creating an onchain transaction is accomplished via the Create Onchain Transaction endpoint. While this endpoint processes the initiation of a transaction, please note:

The transaction still requires signing through the standard Onchain wallet flows.
Consensus approval still applies if required by the portfolio’s transfer rules.

When specifying the chain ID, it is important to remember that it is a numeric code representing the blockchain network. For example, the chain ID for Base is 8453. Other network codes can be looked up at Chainlist. For how to build the raw_unsigned_txn value for EVM and Solana transactions, including contract calls, see Building the raw unsigned transaction. See below for an example request.

TransactionsService transactionsService = PrimeServiceFactory.createOnchainTransaction(client);

EvmParams evmParams = new EvmParams.Builder()
.chainId("CHAIN_ID_HERE")
.build();

CreateOnchainTransactionRequest request = new CreateOnchainTransactionRequest.Builder()
.portfolioId("PORTFOLIO_ID_HERE")
.walletId("WALLET_ID_HERE")
.rawUnsignedTransaction("RAW_UNSIGNED_TRANSACTION_HERE")
.evmParams(evmParams)
.amount("AMOUNT")
.build();

CreateOnchainTransactionResponse response = transactionsService.createOnchainTransaction(request);

To learn more about this SDK, please visit the Prime Java SDK.

var transactionsService = new OnchainTransactionsService(client);

var evmParams = new EvmParams
{
    ChainId               = "CHAIN_ID_HERE"
};

var request = new CreateOnchainTransactionRequest
{
    PortfolioId           = "PORTFOLIO_ID_HERE",
    WalletId              = "WALLET_ID_HERE",
    RawUnsignedTransaction = "RAW_UNSIGNED_TRANSACTION_HERE",
    EvmParams             = evmParams,
    Amount                = "AMOUNT"
};

var response = transactionsService.CreateOnchainTransaction(request);

To learn more about this SDK, please visit the Prime .NET SDK.

func createOnchainTransactionExample() {
transactionsService := transactions.NewOnchainTransactionsService(client)

evmParams := &transactions.EvmParams{
ChainId:               "CHAIN_ID_HERE",
}

request := &transactions.CreateOnchainTransactionRequest{
PortfolioId:           "PORTFOLIO_ID_HERE",
WalletId:              "WALLET_ID_HERE",
RawUnsignedTransaction: "RAW_UNSIGNED_TRANSACTION_HERE",
EvmParams:            evmParams,
Amount:               "AMOUNT",
}

response, err := transactionsService.CreateOnchainTransaction(context.Background(), request)
}

To learn more about this SDK, please visit the Prime Go SDK.

from prime_sdk.credentials import Credentials
from prime_sdk.client import Client
from prime_sdk.services.transactions import TransactionsService, CreateOnchainTransactionRequest, EvmParams

credentials = Credentials.from_env("PRIME_CREDENTIALS")
client = Client(credentials)
transactions_service = TransactionsService(client)

evm_params = EvmParams(
    chain_id="CHAIN_ID_HERE"
)

request = CreateOnchainTransactionRequest(
    portfolio_id="PORTFOLIO_ID_HERE",
    wallet_id="WALLET_ID_HERE",
    raw_unsigned_transaction="RAW_UNSIGNED_TRANSACTION_HERE",
    evm_params=evm_params,
    amount="AMOUNT"
)

response = transactions_service.create_onchain_transaction(request)

To learn more about this SDK, please visit the Prime Python SDK.

primectl create-onchain-transaction --help

const transactionsService = new OnchainTransactionsService(client);

const evmParams = {
chainId: "CHAIN_ID_HERE"
};

const request = {
portfolioId: "PORTFOLIO_ID_HERE",
walletId: "WALLET_ID_HERE",
rawUnsignedTransaction: "RAW_UNSIGNED_TRANSACTION_HERE",
evmParams,
amount: "AMOUNT"
};

transactionsService.createOnchainTransaction(request)
.then(response => {
console.log('Onchain Transaction Response:', response);
})

Building the raw unsigned transaction

The raw_unsigned_txn field takes a complete, unsigned transaction, serialized and hex-encoded. A leading 0x is optional. Prime signs the transaction with the wallet in the request path, so the transaction does not need a sender field or a signature. The examples below use Python and reproduce the EVM and Solana examples in the API reference. Install the Python packages used in the examples:

pip install rlp eth-utils eth-abi web3 solders solana

Dynamic nonce and gas (EVM)

By default, Prime sets the nonce and gas fees of EVM transactions before signing (evm_params.disable_dynamic_nonce and evm_params.disable_dynamic_gas both default to false). With these defaults, set the nonce and fee fields to 0 in the transaction you build. To control either value yourself, set it in the transaction and set the matching disable_dynamic_* option to true. To speed up or cancel a pending transaction, pass its ID in evm_params.replaced_transaction_id and leave dynamic nonce enabled.

{
  "raw_unsigned_txn": "02e60180808080942225166893d26f2064a15cc84f5b897591a7e6938642a13798e59d80c0808080",
  "evm_params": {
    "chain_id": "1",
    "disable_dynamic_nonce": false,
    "disable_dynamic_gas": false
  }
}

EVM transactions

Prime expects EIP-1559 (type 2) transactions. Fields in an RLP-encoded transaction are positional, so a field you want Prime to set is encoded as 0 rather than omitted.

In RLP, the integer 0 is encoded as the single byte 0x80 (an empty string), not 0x00. The rlp package used below handles this for you. If you encode the transaction another way, write 0x80 for each zero-valued field.

import rlp
from eth_utils import to_canonical_address

def build_evm_unsigned(chain_id: int, to: str, value_wei: int, data: bytes = b"",
                       nonce: int = 0, max_priority_fee: int = 0,
                       max_fee: int = 0, gas: int = 0) -> str:
    fields = [
        chain_id, nonce, max_priority_fee, max_fee, gas,
        to_canonical_address(to), value_wei, data,
        [],       # access list
        0, 0, 0,  # empty signature fields (y_parity, r, s): required in the structure,
                  # overwritten by Prime at signing
    ]
    return (b"\x02" + rlp.encode(fields)).hex()

raw_unsigned_txn = build_evm_unsigned(
    chain_id=1,
    to="0x2225166893d26f2064a15cc84f5b897591a7e693",
    value_wei=73_260_189_935_005,
)

evm_params is required for EVM wallets and must include chain_id. Set the chain ID in the transaction and in evm_params.chain_id, and make sure they match.

Transaction	`to`	`value_wei`	`data`
Native asset transfer (ETH, POL)	Recipient address	Amount in wei	`b""`
Contract call, such as an ERC-20 transfer	Contract address	`0`	Encoded function call
Payable contract call, such as a WETH deposit	Contract address	Native amount sent with the call	Encoded function call

Encoding contract calls (EVM)

For a contract call, data is the 4-byte function selector followed by the ABI-encoded arguments. The selector is the first 4 bytes of the Keccak-256 hash of the canonical function signature, such as transfer(address,uint256). If you have the contract’s ABI, for example from the contract’s verified source on a block explorer, use web3.py to encode the call. The ABI entry validates the argument types for you.

from web3 import Web3

USDC = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
ERC20_TRANSFER_ABI = [{
    "name": "transfer", "type": "function", "stateMutability": "nonpayable",
    "inputs": [{"name": "to", "type": "address"}, {"name": "amount", "type": "uint256"}],
    "outputs": [{"name": "", "type": "bool"}],
}]

contract = Web3().eth.contract(address=USDC, abi=ERC20_TRANSFER_ABI)
data = bytes.fromhex(contract.encode_abi(
    "transfer",
    args=[Web3.to_checksum_address("0x2225166893d26f2064a15cc84f5b897591a7e693"), 1_000_000],  # 1 USDC (6 decimals)
)[2:])

raw_unsigned_txn = build_evm_unsigned(chain_id=1, to=USDC, value_wei=0, data=data)

If you only know the function signature, encode the selector and arguments directly. Write the signature with canonical types (uint256, not uint), no spaces, and no parameter names.

from eth_abi import encode
from eth_utils import function_signature_to_4byte_selector

def encode_call(signature: str, arg_types: list[str], args: list) -> bytes:
    return function_signature_to_4byte_selector(signature) + encode(arg_types, args)

data = encode_call(
    "transfer(address,uint256)",
    ["address", "uint256"],
    ["0x2225166893d26f2064a15cc84f5b897591a7e693", 1_000_000],
)

Struct arguments are encoded as tuples. List the struct’s field types in parentheses, and pass the value as a Python tuple in field order. For example, Uniswap V3 exactInputSingle:

token_in = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"        # USDC
token_out = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"       # WETH
swap_recipient = "0x2225166893d26f2064a15cc84f5b897591a7e693"
amount_in = 1_000_000                                          # 1 USDC (6 decimals)
amount_out_minimum = 0                                         # set a real slippage limit in production

params_type = "(address,address,uint24,address,uint256,uint256,uint160)"
data = encode_call(
    f"exactInputSingle({params_type})",
    [params_type],
    [(token_in, token_out, 500, swap_recipient, amount_in, amount_out_minimum, 0)],
)

Solidity type	Python value
`address`	Hex string (`"0x..."`). web3.py requires checksummed addresses; convert with `Web3.to_checksum_address`.
`uint256`, `uint24`, `int256`, and other integers	`int`, in the token’s base units (amount × 10^decimals)
`bool`	`True` or `False`
`bytes32`, `bytes`	`bytes`
`string`	`str`
`address[]`, `uint256[]`, and other arrays	`list`
Struct	`tuple`, fields in declaration order

Token decimals vary. USDC and USDT use 6 decimals, and most other ERC-20 tokens use 18. For proxy contracts, use the implementation contract’s ABI with the proxy address as to. To check your encoding, decode it with contract.decode_function_input(data) before submitting.

Solana transactions

Prime expects a versioned (v0) transaction with an empty signature slot for the Prime Onchain Wallet in the request path. In the common case, the Onchain Wallet is the fee payer and the only signer, as in the examples below. If the transaction requires other signers, collect their signatures before you submit it: Prime adds its signature to the first empty signature slot. Omit evm_params for Solana wallets. Requests that include it are rejected.

from solders.hash import Hash
from solders.message import MessageV0
from solders.pubkey import Pubkey
from solders.signature import Signature
from solders.transaction import VersionedTransaction

def build_solana_unsigned(payer: Pubkey, instructions: list, blockhash: Hash) -> str:
    message = MessageV0.try_compile(payer, instructions, [], blockhash)
    tx = VersionedTransaction.populate(message, [Signature.default()])  # empty signature slot
    return bytes(tx).hex()

When Prime signs a transaction whose signature slots are all empty, it replaces the transaction’s blockhash with a recent one. You don’t need to fetch a blockhash yourself; any value works, such as the all-zero default:

blockhash = Hash.default()  # replaced with a recent blockhash when Prime signs

If the transaction already includes another signer’s signature, Prime does not replace the blockhash, because changing it would invalidate that signature. Build the transaction with a recent blockhash, for example from Client(rpc_url).get_latest_blockhash().value.blockhash in solana-py.A blockhash expires after about 150 blocks (roughly one minute), and the transaction must be approved, signed, and broadcast before then. If the portfolio requires consensus approval, the transaction can expire before it is approved.

The instructions you pass determine what the transaction does. A native SOL transfer, with optional compute budget instructions that set a priority fee:

from solders.compute_budget import set_compute_unit_limit, set_compute_unit_price
from solders.system_program import transfer, TransferParams

payer = Pubkey.from_string("YOUR_ONCHAIN_WALLET_ADDRESS")
recipient = Pubkey.from_string("RECIPIENT_ADDRESS")

instructions = [
    transfer(TransferParams(from_pubkey=payer, to_pubkey=recipient, lamports=1_461_046)),
    set_compute_unit_price(10_000),   # priority fee, in micro-lamports per compute unit
    set_compute_unit_limit(200_000),
]
raw_unsigned_txn = build_solana_unsigned(payer, instructions, blockhash)

An SPL token transfer, such as USDC. The transfer goes to the recipient’s associated token account for the mint. The idempotent create instruction creates that account if it doesn’t exist yet and does nothing if it does, so you can always include it.

from spl.token.constants import TOKEN_PROGRAM_ID
from spl.token.instructions import (
    create_idempotent_associated_token_account, get_associated_token_address, transfer_checked,
)
from spl.token.models import TransferCheckedParams

usdc_mint = Pubkey.from_string("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")

instructions = [
    create_idempotent_associated_token_account(payer=payer, owner=recipient, mint=usdc_mint),
    transfer_checked(TransferCheckedParams(
        program_id=TOKEN_PROGRAM_ID,
        source=get_associated_token_address(payer, usdc_mint),
        mint=usdc_mint,
        dest=get_associated_token_address(recipient, usdc_mint),
        owner=payer,
        amount=1_000_000,  # 1 USDC (6 decimals)
        decimals=6,
    )),
]
raw_unsigned_txn = build_solana_unsigned(payer, instructions, blockhash)

A call to a custom program. Take the account order, signer and writable flags, and argument layout from the program’s IDL. For programs built with Anchor, the instruction data starts with an 8-byte discriminator, followed by the Borsh-encoded arguments.

import hashlib
import struct
from solders.instruction import AccountMeta, Instruction

discriminator = hashlib.sha256(b"global:INSTRUCTION_NAME").digest()[:8]
data = discriminator + struct.pack("<Q", 1_000_000)  # a single u64 argument

instruction = Instruction(
    program_id=Pubkey.from_string("PROGRAM_ID"),
    data=data,
    accounts=[
        AccountMeta(pubkey=payer, is_signer=True, is_writable=True),
        AccountMeta(pubkey=Pubkey.from_string("OTHER_ACCOUNT"), is_signer=False, is_writable=True),
    ],
)
raw_unsigned_txn = build_solana_unsigned(payer, [instruction], blockhash)

Common mistakes

Mistake	Fix
Base64 or base58 encoding	Hex-encode the serialized bytes.
Amounts in ETH, SOL, or whole tokens	Use base units: wei, lamports, or amount × 10^decimals.
Chain ID in the transaction differs from `evm_params.chain_id`	Use the same chain ID in both.
`evm_params` included for a Solana wallet	Omit `evm_params`; it’s required for EVM wallets only.
Other required Solana signers haven’t signed	Collect their signatures before submitting.

GET STARTED

AI AGENTS

WALLETS

PAYMENTS

STABLECOINS

TRADING

ONCHAIN TOOLS

CUSTOMERS

WEBHOOKS

CONSUMER APIS

BUSINESS APIS

INSTITUTIONAL APIS

Creating an Onchain Wallet

Receiving funds into Prime Onchain Wallet

Address groups

Creating an onchain transaction

Building the raw unsigned transaction

Dynamic nonce and gas (EVM)

EVM transactions

Encoding contract calls (EVM)

Solana transactions

Common mistakes

​Creating an Onchain Wallet

​Receiving funds into Prime Onchain Wallet

​Address groups

​Creating an onchain transaction

​Building the raw unsigned transaction

​Dynamic nonce and gas (EVM)

​EVM transactions

​Encoding contract calls (EVM)

​Solana transactions

​Common mistakes

Creating an Onchain Wallet

Receiving funds into Prime Onchain Wallet

Address groups

Creating an onchain transaction

Building the raw unsigned transaction

Dynamic nonce and gas (EVM)

EVM transactions

Encoding contract calls (EVM)

Solana transactions

Common mistakes