Skip to main content

Transaction Build Guide

This guide explains how to create the original transaction to be signed (serializedUnsignedTransaction). The value created here is used as the input of the Octet Request Withdrawal or Request Transaction Signing API.



Bitcoin​

Bitcoin is UTXO-based, so you need the list of UTXOs held by the sending address. UTXOs can be looked up with the Octet Get UTXO List API.

  • utxos: The list of UTXOs held by the sending address. Use the txid, outputIndex (→ vout), and script from the Get UTXO List API response as they are; amount is in BTC, so convert it to satoshi and put it in value.
  • feeRate: The fee rate (sat/vByte). It can be looked up with the Octet Get Fee of Asset Registered in Wallet API; the withdrawalFee.gasPrice value in the response corresponds to the Bitcoin fee rate (sat/vByte).
  • coinselect selects the UTXOs to use, taking the fee into account, and calculates the change output.
  • Octet's default Bitcoin address type is P2WPKH (SegWit, starting with bc1), so the example is also based on P2WPKH and builds the input with witnessUtxo. The build output is a PSBT hex.
  • Bitcoin does not support the Request Transaction Signing API, so the PSBT created here is for withdrawal requests only.
// bitcoinjs-lib: 6.1.7
// coinselect: 3.1.13
import * as bitcoin from 'bitcoinjs-lib';
const coinSelect = require('coinselect');

/*
NETWORK
mainnet: bitcoin.networks.bitcoin
testnet: bitcoin.networks.testnet
*/
const network = bitcoin.networks.bitcoin;

const fromAddress = 'bc1qm3p027vycz73t99ewclkjz53c4qkyswmcnwve9'; // sending address (change recipient address)
const toAddress = 'bc1ql6tme8r3wk88nuldy2eguaz7rgtg0efhl7h9v7'; // receiving address
const amount = 6000000; // amount to send (satoshi)
const feeRate = 10; // fee rate (sat/vByte, withdrawalFee.gasPrice from the fee lookup API response)

// list of UTXOs held by the sending address (looked up with the Get UTXO List API)
const utxos = [
{
txid: 'ff219ded839a14010222985c4f314f123a50b5d6984c8c8d41f1ad037ef8e9a9', // UTXO transaction hash
vout: 1, // UTXO output index (outputIndex from the lookup response)
value: 5000000, // UTXO amount (satoshi)
script: '0014dc42f57984c0bd1594b9763f690a91c5416241db', // scriptPubKey of the UTXO (hex)
},
{
txid: 'b4f5e8a209cc41d6d24f7f8ccde3f7a5be9d9ad3ad3f7f6a30cf50f4406eab12',
vout: 0,
value: 3000000,
script: '0014dc42f57984c0bd1594b9763f690a91c5416241db',
},
];

// calculate the inputs and outputs (including change) to use, taking the fee into account
const { inputs, outputs } = coinSelect(utxos, [{ address: toAddress, value: amount }], feeRate);
if (!inputs || !outputs) {
throw new Error('Insufficient funds');
}

const psbt = new bitcoin.Psbt({ network });

for (const input of inputs) {
psbt.addInput({
hash: Buffer.from(input.txid, 'hex').reverse(), // convert txid to little-endian
index: input.vout,
witnessUtxo: {
script: Buffer.from(input.script, 'hex'),
value: input.value,
},
});
}

for (const output of outputs) {
// an output without an address is change, so return it to the sending address
psbt.addOutput({
address: output.address ?? fromAddress,
value: output.value,
});
}

const serializedUnsignedTransaction = psbt.toHex();
// 70736274ff01009a0200000002a9e9f87e03adf1418d8c4c98d6b5503a124f314f5c98220201149a83ed9d21ff0100000000ffffffff12ab6e40f450cf306a7f3fadd39a9dbea5f7e3cd8c7f4fd2d641cc09a2e8f5b40000000000ffffffff02808d5b0000000000160014fe97bc9c71758e79f3ed22b28e745e1a1687e537d07a1e0000000000160014dc42f57984c0bd1594b9763f690a91c5416241db000000000001011f404b4c0000000000160014dc42f57984c0bd1594b9763f690a91c5416241db0001011fc0c62d0000000000160014dc42f57984c0bd1594b9763f690a91c5416241db000000


Ethereum family (EVM)​

Ethereum, Arbitrum, Polygon, Avalanche, and BNB Smart Chain are all built the same way; the only differences between platforms are the CHAIN_ID and the supported transaction types.

PlatformCHAIN_ID (mainnet)CHAIN_ID (testnet)Supported transaction types
Ethereum111155111 (Sepolia)EIP-1559, Legacy
Arbitrum42161421614 (Sepolia)EIP-1559, Legacy
Polygon13780002 (Amoy)EIP-1559, Legacy
Avalanche4311443113 (Fuji)EIP-1559, Legacy
BNB Smart Chain5697Legacy only (EIP-1559 not supported)
  • nonce: The transaction count of the sending address (looked up with eth_getTransactionCount)
  • maxFeePerGas / maxPriorityFeePerGas: EIP-1559 gas prices (gwei). Legacy transactions use only gasPrice.
  • The gasLimit for a native coin transfer is fixed at 21000; for token transfers it differs by token, so set it generously or estimate it with eth_estimateGas.
  • Transactions used for a withdrawal request may only be native coin transfers or ERC-20 transfer calls (any other calldata is rejected). A transaction signing request allows arbitrary calldata.
  • Examples are provided in both TypeScript (@ethereumjs/tx) and Java (web3j 4.12.x, JDK 17). The unsigned serialization formats of the two libraries differ (whether signature placeholders are present), so their outputs differ, but Octet handles both the same way.

EIP-1559 — Native coin transfer​

The example below is based on Ethereum; for Arbitrum, Polygon, and Avalanche, just change the CHAIN_ID according to the table above.

// @ethereumjs/tx: 5.4.0
// @ethereumjs/common: 4.4.0
// web3: 4.16.0
import { FeeMarketEIP1559Transaction } from '@ethereumjs/tx';
import { Common } from '@ethereumjs/common';
import { Web3 } from 'web3';

const web3 = new Web3();

/*
CHAIN_ID
mainnet: 1
testnet(sepolia): 11155111
*/
const CHAIN_ID = 1;
const HARDFORK = 'london';

const toAddress = '0x4c81fec94ab7a764667ad35b55190cbeb4cd4a34'; // receiving address
const amount = '0.02'; // amount to send (ETH)
const nonce = 0; // transaction count of the sending address (eth_getTransactionCount)
const maxFeePerGasGwei = '41'; // maximum gas price (gwei)
const maxPriorityFeePerGasGwei = '1'; // priority fee (gwei)

const txData: any = {
type: '0x02',
nonce: web3.utils.toHex(nonce),
to: toAddress,
value: web3.utils.toHex(BigInt(web3.utils.toWei(amount, 'ether'))),
gasLimit: web3.utils.toHex(21000),
maxFeePerGas: web3.utils.toHex(BigInt(web3.utils.toWei(maxFeePerGasGwei, 'gwei'))),
maxPriorityFeePerGas: web3.utils.toHex(BigInt(web3.utils.toWei(maxPriorityFeePerGasGwei, 'gwei'))),
};

const common = Common.custom({ chainId: CHAIN_ID }, { hardfork: HARDFORK });
const tx = FeeMarketEIP1559Transaction.fromTxData(txData, { common });

const serializedUnsignedTransaction = `0x${Buffer.from(tx.serialize()).toString('hex')}`;
// 0x02f20180843b9aca0085098bca5a00825208944c81fec94ab7a764667ad35b55190cbeb4cd4a3487470de4df82000080c0808080

The output of the TypeScript example is identical to the input of the Ethereum example in the transaction signing guide.

EIP-1559 — ERC-20 token transfer​

ABI-encode the contract's transfer(to, value) call and put it in data, and set to to the token contract address. Pass value (the transfer amount) as an integer in the smallest unit with the token's decimals applied.

// @ethereumjs/tx: 5.4.0
// @ethereumjs/common: 4.4.0
// web3: 4.16.0
import { FeeMarketEIP1559Transaction } from '@ethereumjs/tx';
import { Common } from '@ethereumjs/common';
import { Web3, Contract } from 'web3';

const web3 = new Web3();

/*
CHAIN_ID
mainnet: 1
testnet(sepolia): 11155111
*/
const CHAIN_ID = 1;
const HARDFORK = 'london';

const Erc20TransferAbi: any = [
{
inputs: [
{ name: '_to', type: 'address' },
{ name: '_value', type: 'uint256' },
],
name: 'transfer',
outputs: [{ name: '', type: 'bool' }],
stateMutability: 'nonpayable',
type: 'function',
},
];

const contractAddress = '0xdac17f958d2ee523a2206206994597c13d831ec7'; // token contract address (example: USDT)
const toAddress = '0x4c81fec94ab7a764667ad35b55190cbeb4cd4a34'; // receiving address
const amount = '12500000'; // amount to send - smallest unit with the token decimals applied (12.5 USDT, decimals: 6)
const nonce = 0; // transaction count of the sending address (eth_getTransactionCount)
const maxFeePerGasGwei = '41'; // maximum gas price (gwei)
const maxPriorityFeePerGasGwei = '1'; // priority fee (gwei)

const contract = new Contract(Erc20TransferAbi, contractAddress);
const data = contract.methods.transfer(toAddress, amount).encodeABI();

const txData: any = {
type: '0x02',
nonce: web3.utils.toHex(nonce),
to: contractAddress,
value: '0x0',
data,
gasLimit: web3.utils.toHex(100000),
maxFeePerGas: web3.utils.toHex(BigInt(web3.utils.toWei(maxFeePerGasGwei, 'gwei'))),
maxPriorityFeePerGas: web3.utils.toHex(BigInt(web3.utils.toWei(maxPriorityFeePerGasGwei, 'gwei'))),
};

const common = Common.custom({ chainId: CHAIN_ID }, { hardfork: HARDFORK });
const tx = FeeMarketEIP1559Transaction.fromTxData(txData, { common });

const serializedUnsignedTransaction = `0x${Buffer.from(tx.serialize()).toString('hex')}`;
// 0x02f8710180843b9aca0085098bca5a00830186a094dac17f958d2ee523a2206206994597c13d831ec780b844a9059cbb0000000000000000000000004c81fec94ab7a764667ad35b55190cbeb4cd4a340000000000000000000000000000000000000000000000000000000000bebc20c0808080

Legacy — BNB Smart Chain​

BNB Smart Chain does not support EIP-1559, so you must build a Legacy transaction (gasPrice). For a BEP-20 token transfer, encode data the same way as in the ERC-20 example above, and build with LegacyTransaction + gasPrice as shown below. The same kind of Legacy transaction can also be used on Ethereum, Arbitrum, Polygon, and Avalanche.

// @ethereumjs/tx: 5.4.0
// @ethereumjs/common: 4.4.0
// web3: 4.16.0
import { LegacyTransaction } from '@ethereumjs/tx';
import { Common } from '@ethereumjs/common';
import { Web3 } from 'web3';

const web3 = new Web3();

/*
CHAIN_ID
mainnet: 56
testnet: 97
*/
const CHAIN_ID = 56;

const toAddress = '0x4c81fec94ab7a764667ad35b55190cbeb4cd4a34'; // receiving address
const amount = '0.02'; // amount to send (BNB)
const nonce = 0; // transaction count of the sending address (eth_getTransactionCount)
const gasPriceGwei = '41'; // gas price (gwei)

const txData: any = {
nonce: web3.utils.toHex(nonce),
to: toAddress,
value: web3.utils.toHex(BigInt(web3.utils.toWei(amount, 'ether'))),
gasLimit: web3.utils.toHex(21000),
gasPrice: web3.utils.toHex(BigInt(web3.utils.toWei(gasPriceGwei, 'gwei'))),
};

const common = Common.custom({ chainId: CHAIN_ID });
const tx = LegacyTransaction.fromTxData(txData, { common });

const serializedUnsignedTransaction = `0x${Buffer.from(tx.serialize()).toString('hex')}`;
// 0xeb8085098bca5a00825208944c81fec94ab7a764667ad35b55190cbeb4cd4a3487470de4df82000080808080

The output of the TypeScript example is identical to the input of the BNB Smart Chain example in the transaction signing guide.



Klaytn (Kaia)​

Klaytn transactions are built with caver-js (TypeScript) or caver-java (Java). The allowed transaction types differ by API, so refer to the table below.

Transaction typeRequest WithdrawalRequest Transaction Signing
TxTypeLegacyTransaction✅✅
TxTypeValueTransfer✅✅
TxTypeSmartContractExecution✅ (KIP-7/ERC-20 transfer calls only)✅ (arbitrary calls allowed)
TxTypeSmartContractDeploy❌✅
TxTypeFeeDelegatedValueTransfer✅✅
TxTypeFeeDelegatedSmartContractExecution✅ (transfer calls only)✅ (arbitrary calls allowed)
TxTypeFeeDelegatedSmartContractDeploy❌✅
TxTypeEthereumDynamicFee❌❌
  • Legacy: The Ethereum-compatible type. A value built with LegacyTransaction from @ethereumjs/tx, as in the BNB Smart Chain example, can also be used.
  • FeeDelegated family (fee delegation): useFeeDelegation: true is required when requesting (conversely, useFeeDelegation cannot be turned on for non-fee-delegated types), and the transaction's feePayer must be left empty or set to the wallet's fee address. The network fee of a fee-delegated transaction is paid by the wallet's fee address, and Octet adds the feePayer signature.

chainId is not included in the serialization result (RLP) of Kaia-type transactions, and the Octet server uses the platform setting when computing the signing target, so you do not need to specify it when building. The chainId included in Legacy-type transactions is also replaced with the platform setting. gasPrice is in ston (1 ston = 10⁹ peb, equivalent to gwei on Ethereum), and you use the withdrawalFee.gasPrice value from the Get Fee of Asset Registered in Wallet API response.

Native coin transfer​

// caver-js: 1.8.1
import Caver from 'caver-js';

const caver = new Caver();

const fromAddress = '0xdc42f57984c0bd1594b9763f690a91c5416241db'; // sending address
const toAddress = '0x4c81fec94ab7a764667ad35b55190cbeb4cd4a34'; // receiving address
const amount = '0.02'; // amount to send (KAIA)
const nonce = 0; // transaction count of the sending address (klay_getTransactionCount)
const gasPriceSton = '27.5'; // gas price (ston, withdrawalFee.gasPrice from the fee lookup API response)

const tx = caver.transaction.valueTransfer.create({
from: fromAddress,
to: toAddress,
value: caver.utils.toPeb(amount, 'KLAY'),
gas: 21000,
gasPrice: caver.utils.numberToHex(caver.utils.toPeb(gasPriceSton, 'ston')),
nonce,
});

const serializedUnsignedTransaction = tx.getRLPEncoding();
// 0x08f8418085066720b300825208944c81fec94ab7a764667ad35b55190cbeb4cd4a3487470de4df82000094dc42f57984c0bd1594b9763f690a91c5416241dbc4c3018080

KIP-7 (ERC-20) token transfer​

ABI-encode the contract's transfer(to, value) call and put it in input, and set to to the token contract address. Pass value (the transfer amount) as an integer in the smallest unit with the token's decimals applied.

// caver-js: 1.8.1
import Caver from 'caver-js';

const caver = new Caver();

const contractAddress = '0x59a6ab7c6ec2b1e70b47d90b0e094fa2f5e27a31'; // token contract address
const fromAddress = '0xdc42f57984c0bd1594b9763f690a91c5416241db'; // sending address
const toAddress = '0x4c81fec94ab7a764667ad35b55190cbeb4cd4a34'; // receiving address
const amount = '12500000'; // amount to send - smallest unit with the token decimals applied
const nonce = 0; // transaction count of the sending address (klay_getTransactionCount)
const gasPriceSton = '27.5'; // gas price (ston)

const input = caver.abi.encodeFunctionCall(
{
name: 'transfer',
type: 'function',
inputs: [
{ type: 'address', name: '_to' },
{ type: 'uint256', name: '_value' },
],
},
[toAddress, amount],
);

const tx = caver.transaction.smartContractExecution.create({
from: fromAddress,
to: contractAddress,
value: 0,
input,
gas: 100000,
gasPrice: caver.utils.numberToHex(caver.utils.toPeb(gasPriceSton, 'ston')),
nonce,
});

const serializedUnsignedTransaction = tx.getRLPEncoding();
// 0x30f8818085066720b300830186a09459a6ab7c6ec2b1e70b47d90b0e094fa2f5e27a318094dc42f57984c0bd1594b9763f690a91c5416241dbb844a9059cbb0000000000000000000000004c81fec94ab7a764667ad35b55190cbeb4cd4a340000000000000000000000000000000000000000000000000000000000bebc20c4c3018080