transactions_encode

Overview

Encode a transaction into BCS (Binary Canonical Serialization) bytes ready for signing. This endpoint is the bridge between transaction construction and offline signing workflows. It takes a complete transaction object (without signature) and returns the canonical byte representation that must be signed to produce a valid signed transaction.

Endpoint

POST /v1/transactions/encode_submission

Code Examples

Encoding Workflow

The complete encode-sign-submit workflow:

Text

1. GET /v1/accounts/{address}          → sequence_number
2. GET /v1/estimate_gas_price          → gas_unit_price
3. Build transaction JSON              → raw transaction object
4. POST /v1/transactions/encode_submission → BCS-encoded bytes
5. Sign encoded bytes (offline)        → signature
6. POST /v1/transactions               → submit signed transaction
7. GET /v1/transactions/by_hash/{hash} → confirm execution

This separation enables secure signing workflows where the signing key never touches a networked machine.

Use Cases

Offline Signing: Encode transactions on an online machine, transfer encoded bytes to an air-gapped signing device, then return signatures for submission. This is the gold standard for securing high-value operations.
Hardware Wallet Integration: Send encoded transaction bytes to hardware wallets (Ledger, Trezor) for signing, maintaining security while using blockchain APIs for transaction construction.
Multi-Step Approval Workflows: Separate transaction construction, review, approval, and signing into distinct steps for organizational governance. Each step can be handled by different systems or personnel.
Cross-Platform Signing: Encode on a server (web API) and sign on a different platform (mobile app, desktop wallet) without requiring the full Aptos SDK on both sides.
Transaction Inspection: Encode transactions to verify their exact on-chain representation before signing. Compare encoded bytes against expected values for audit and verification.
Custodial Architectures: In custodial wallet systems, the hot system builds and encodes transactions while the cold signing system only handles encoded bytes and produces signatures.

Best Practices

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

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

Expiration Timestamps: Set expiration_timestamp_secs to current time + 60-120 seconds. Factor in the time needed for the signing round trip when using offline signing -- add extra time for hardware wallet interactions.

Chain ID Verification: The encoding implicitly uses the node's chain ID. Ensure you are encoding against the correct network (mainnet vs testnet) to prevent cross-network issues.

Byte Handling: The returned hex string is 0x-prefixed. Remove the 0x prefix before converting to byte arrays for signing. Most signing libraries expect raw bytes, not hex strings.

Encoding Validation: After encoding, optionally decode the bytes client-side to verify correctness before sending to signing devices. This catches errors before they reach expensive hardware signing steps.

Security Considerations

Encoding itself does not involve cryptographic keys or sensitive data. However, the encoded bytes represent a transaction ready for signing -- treat them as sensitive in the following ways:

Verify before signing: Always display or log the human-readable transaction details alongside encoded bytes so signers can verify what they are approving.
Secure transport: When transmitting encoded bytes to signing devices, use authenticated channels to prevent man-in-the-middle modification.
Tamper detection: Any modification to the encoded bytes produces a different signature that will be rejected by the network, providing built-in tamper evidence.

Performance Considerations

Encoding is a fast, computational operation that validates the transaction against on-chain state (verifying the function exists, types match, etc.) but does not execute it. 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-1,000 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.

/v1/transactions - Submit the signed transaction
/v1/transactions/simulate - Simulate before encoding and signing
/v1/accounts/{address} - Get current sequence number
/v1/estimate_gas_price - Get gas price for transaction building
/v1/transactions/by_hash/{hash} - Check submitted transaction status

On this page