⚠️Blast API (blastapi.io) ends Oct 31. Migrate to Dwellir and skip Alchemy's expensive compute units.
Switch Today →
Skip to main content

transactions_encode

Endpoint#

POST /v1/transactions/encode_submission

Request Body#

{
  "sender": "0x..",
  "sequence_number": "..",
  "payload": { "type": "entry_function_payload", "function": "0x1::aptos_account::transfer", "type_arguments": ["0x1::aptos_coin::AptosCoin"], "arguments": ["0x2","1000"] }
}

Response#

Success Response (200)#

Returns the BCS-encoded transaction bytes as a hex string:

{
  "encoded": "0xb5e97db07fa0bd0e5598aa3643a9bc6f6693bddc1a9fec9e674a461eaa00b193..."
}

These bytes can be signed and submitted without additional encoding.

Error Responses#

StatusError CodeDescription
400invalid_inputInvalid transaction format or missing required fields
400invalid_payloadPayload doesn't conform to entry function or script requirements

Code Examples#

curl -s -X POST "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/encode_submission" \
  -H "Content-Type: application/json" \
  -d '{"sender":"0x...","sequence_number":"1","payload":{"type":"entry_function_payload","function":"0x1::aptos_account::transfer","type_arguments":["0x1::aptos_coin::AptosCoin"],"arguments":["0x2","1000"]}}'

Python workflow:

from aptos_sdk.client import RestClient
from aptos_sdk.account import Account

client = RestClient("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1")
account = Account.load_key("private_key_hex")

# Build transaction
raw_txn = {...}  # Transaction object
encoded = client.encode_submission(raw_txn)

# Sign encoded bytes
signature = account.sign(bytes.fromhex(encoded['encoded'][2:]))

# Submit signed transaction
client.submit_transaction({...})

Use Cases#

Transaction encoding serves several important purposes:

  1. Offline Signing: Encode transactions on an online machine, transfer encoded bytes to an air-gapped signing device, then return signatures for submission without exposing private keys to networked systems.

  2. Hardware Wallet Integration: Send encoded transaction bytes to hardware wallets (Ledger, Trezor) for signing, maintaining security while using blockchain APIs.

  3. Multi-Step Workflows: Separate transaction construction, approval, signing, and submission into distinct steps, useful for organizational approval processes.

  4. Cross-Platform Signing: Encode on one platform (web API) and sign on another (mobile app, desktop wallet) without requiring full SDK on both sides.

  5. Transaction Inspection: Encode transactions to get their exact on-chain representation before signing, useful for verification and auditing.

  6. Gas Estimation: Generate encoded transactions for simulation to accurately estimate gas costs before actual signing and submission.

Best Practices#

Complete Transaction Fields: Include all required fields: sender, sequence_number, max_gas_amount, gas_unit_price, expiration_timestamp_secs, payload, and chain_id. Missing fields cause encoding failures.

Sequence Number Management: Fetch the latest sequence number from /v1/accounts/{address} immediately before encoding to avoid conflicts with concurrent transactions.

Expiration Timestamps: Set expiration_timestamp_secs to current time + 60-120 seconds. Too short causes timing issues, too long delays failure detection.

Chain ID Verification: Always verify chain_id matches your target network (1 for mainnet, 2 for testnet) to prevent cross-network replay attacks.

Encoding Validation: After encoding, optionally decode the bytes client-side to verify correctness before sending to signing devices.

Byte Handling: The returned hex string is 0x-prefixed. Remove prefix before converting to byte arrays for signing in most programming languages.

Performance Considerations#

Encoding is a fast, pure computational operation without blockchain state access. Response times are typically 20-50ms, dominated by network latency rather than encoding overhead.

Encoded transaction sizes vary:

  • Simple transfers: ~100-200 bytes
  • Smart contract calls: 300-1000 bytes
  • Complex multi-agent transactions: 1-5KB

These sizes are negligible for modern networks but matter for hardware wallet display limitations and QR code encoding use cases.

Security Considerations#

Encoding itself doesn't involve cryptographic keys or sensitive data. However, the encoded bytes represent a transaction ready for signing. Ensure encoded transactions are transmitted securely to signing devices and not modified in transit, as any tampering would cause signature verification failures.

For maximum security, verify the transaction contents (recipient, amount, function being called) on the signing device's display before approving signatures.