transactions_submit

Overview

Submit a signed transaction to the Aptos blockchain for execution. This is the primary endpoint for writing on-chain state, executing Move entry functions, deploying modules, and transferring assets. The transaction must be properly constructed, signed, and BCS-encoded before submission.

Endpoint

POST /v1/transactions

Transaction Signing Flow

The complete submit workflow requires multiple steps:

Get account info -- fetch the current sequence_number from GET /v1/accounts/{address}
Estimate gas -- call GET /v1/estimate_gas_price for current gas pricing
Build the transaction -- construct the payload with all required fields
Encode for signing -- use POST /v1/transactions/encode_submission or client-side BCS encoding
Sign -- sign the encoded bytes with the sender's private key (Ed25519 or MultiEd25519)
Submit -- send the signed transaction to POST /v1/transactions
Confirm -- poll GET /v1/transactions/by_hash/{hash} until committed

Code Examples

Bash

# Submit a pre-signed JSON transaction
curl -s -X POST "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "0x1a2b3c...",
    "sequence_number": "42",
    "max_gas_amount": "2000",
    "gas_unit_price": "100",
    "expiration_timestamp_secs": "1700000120",
    "payload": {
      "type": "entry_function_payload",
      "function": "0x1::aptos_account::transfer",
      "type_arguments": [],
      "arguments": ["0x2a3b4c...", "1000000"]
    },
    "signature": {
      "type": "ed25519_signature",
      "public_key": "0x...",
      "signature": "0x..."
    }
  }'

Use Cases

Token Transfers: Send APT between accounts using 0x1::aptos_account::transfer, or use other entry functions when you need asset-specific transfer flows.
Smart Contract Interaction: Call any published Move entry function to interact with DeFi protocols, NFT marketplaces, or custom applications.
Module Deployment: Publish new Move modules to the blockchain using module_bundle_payload, enabling smart contract deployment and upgrades.
Multi-Agent Transactions: Execute transactions requiring multiple signers, such as atomic swaps or escrow operations.
Governance Voting: Submit votes on on-chain governance proposals through the appropriate governance module entry functions.

Best Practices

Sequence Number Management: Fetch the latest sequence number immediately before building the transaction. For concurrent submissions from the same account, increment locally and handle sequence_number_too_new errors with retries.

Gas Configuration: Use estimate_gas_price for current pricing. Set max_gas_amount higher than expected consumption (simulate first) to avoid out-of-gas failures. Unused gas is not charged.

Expiration Strategy: Set expiration_timestamp_secs to current time + 60-120 seconds. Shorter expirations reduce the window for stale transactions; longer expirations risk mempool bloat.

BCS vs JSON: Use BCS encoding (application/x.aptos.signed_transaction+bcs) in production for smaller payloads and faster processing. JSON encoding is useful for debugging and development.

Idempotency: Resubmitting the same signed transaction is safe. The node deduplicates by hash in the mempool and rejects already-committed transactions with sequence_number_too_old.

Error Recovery: On 429 (rate limited), implement exponential backoff. On sequence_number_too_old, refresh the sequence number and rebuild. On insufficient_balance, check the account balance before retrying.

Performance Considerations

Transaction submission typically completes in 50-200ms (time to enter the mempool). Actual execution occurs in the next 1-3 blocks (4-12 seconds on mainnet).

Transaction size affects submission time: simple transfers are under 500 bytes, while module deployments can reach the maximum transaction size. Larger payloads take longer to transmit and validate.

For high-throughput scenarios, pipeline submissions by incrementing sequence numbers locally rather than waiting for each transaction to confirm before sending the next.

/v1/transactions/encode_submission - Encode transaction for offline signing
/v1/transactions/simulate - Simulate before submitting
/v1/transactions/by_hash/{hash} - Check transaction status
/v1/transactions/wait_by_hash/{hash} - Wait for confirmation
/v1/accounts/{address} - Get current sequence number
/v1/estimate_gas_price - Current gas pricing

On this page