Transactions — Move REST API on Movement

Overview

The transactions endpoint handles both submitting new signed transactions and querying existing ones on Movement. Submitting a transaction is the only way to change on-chain state: transferring tokens, calling entry functions, publishing modules, and interacting with DeFi protocols all require signed transactions.

Movement uses the Aptos transaction format with BCS (Binary Canonical Serialization) encoding. The Aptos SDKs handle serialization and signing automatically, but understanding the format is valuable for debugging and for building custom tooling.

With Movement's fast finality (1-3 seconds), submitted transactions reach a final, irreversible state almost immediately.

Endpoints

Base URL: https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1

Transaction Lifecycle

1. Build -- Construct the transaction payload with sender, sequence number, gas parameters, and the function call.
2. Sign -- Sign the raw transaction bytes with the sender's Ed25519 private key.
3. Submit -- Send the signed transaction to the REST API.
4. Pending -- The transaction enters the mempool and is picked up by the sequencer.
5. Committed -- The transaction is included in a block and executed by the Move VM (1-3 seconds on Movement).
6. Finalized -- On Movement, committed transactions are immediately final due to BFT consensus.

Submit a Transaction

Endpoint

POST /v1/transactions

Headers

When submitting BCS-encoded transactions (recommended), set the content type to application/x.aptos.signed_transaction+bcs and send the raw BCS bytes as the request body. The SDKs handle this automatically.

JSON Submission (Alternative)

You can also submit JSON-encoded transactions with Content-Type: application/json:

{
  "sender": "0xYOUR_ADDRESS",
  "sequence_number": "42",
  "max_gas_amount": "10000",
  "gas_unit_price": "100",
  "expiration_timestamp_secs": "1700000000",
  "payload": {
    "type": "entry_function_payload",
    "function": "0x1::coin::transfer",
    "type_arguments": ["0x1::aptos_coin::AptosCoin"],
    "arguments": ["0xRECIPIENT_ADDRESS", "1000000"]
  },
  "signature": {
    "type": "ed25519_signature",
    "public_key": "0xYOUR_PUBLIC_KEY",
    "signature": "0xSIGNATURE_HEX"
  }
}

Request Fields

Response (202 Accepted)

{
  "hash": "0x7a8c3b1f2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0",
  "sender": "0xYOUR_ADDRESS",
  "sequence_number": "42",
  "max_gas_amount": "10000",
  "gas_unit_price": "100",
  "expiration_timestamp_secs": "1700000000",
  "payload": {
    "type": "entry_function_payload",
    "function": "0x1::coin::transfer",
    "type_arguments": ["0x1::aptos_coin::AptosCoin"],
    "arguments": ["0xRECIPIENT_ADDRESS", "1000000"]
  }
}

The 202 Accepted status means the transaction was received and will be processed. It does not guarantee execution success. Poll by hash to check the outcome.

Transaction Types

Entry Function Payload

The most common type. Calls a public entry function on a published module.

{
  "type": "entry_function_payload",
  "function": "0x1::coin::transfer",
  "type_arguments": ["0x1::aptos_coin::AptosCoin"],
  "arguments": ["0xRECIPIENT", "1000000"]
}

Script Payload

Executes an arbitrary Move script (compiled bytecode) inline. Used for complex multi-step operations that do not have a published module.

{
  "type": "script_payload",
  "code": { "bytecode": "0x..." },
  "type_arguments": [],
  "arguments": []
}

Module Bundle Payload

Publishes Move modules to the sender's account.

{
  "type": "module_bundle_payload",
  "modules": [{ "bytecode": "0x..." }]
}

Query Transactions

By Hash

GET /v1/transactions/by_hash/{txn_hash}

Returns the full transaction details including execution result, gas used, events emitted, and state changes.

By Version

GET /v1/transactions/by_version/{txn_version}

Every committed transaction has a unique, sequential version number. This is useful for indexing and pagination.

Response (Committed Transaction)

{
  "version": "125304892",
  "hash": "0x7a8c3b...",
  "state_change_hash": "0x...",
  "event_root_hash": "0x...",
  "state_checkpoint_hash": "0x...",
  "gas_used": "542",
  "success": true,
  "vm_status": "Executed successfully",
  "accumulator_root_hash": "0x...",
  "changes": [
    {
      "address": "0xYOUR_ADDRESS",
      "state_key_hash": "0x...",
      "data": {
        "type": "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>",
        "data": { "coin": { "value": "999000" } }
      },
      "type": "write_resource"
    }
  ],
  "sender": "0xYOUR_ADDRESS",
  "sequence_number": "42",
  "max_gas_amount": "10000",
  "gas_unit_price": "100",
  "expiration_timestamp_secs": "1700000000",
  "payload": { "..." : "..." },
  "signature": { "..." : "..." },
  "events": [
    {
      "guid": { "creation_number": "3", "account_address": "0xYOUR_ADDRESS" },
      "sequence_number": "8",
      "type": "0x1::coin::WithdrawEvent",
      "data": { "amount": "1000000" }
    }
  ],
  "timestamp": "1699999950000000",
  "type": "user_transaction"
}

Key Response Fields

Code Examples

Transfer Tokens

Query Transaction by Hash

# Get transaction details by hash
TX_HASH="0x7a8c3b1f2e4d5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
curl -s "https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions/by_hash/$TX_HASH" \
  -H "Accept: application/json" | jq '{success, gas_used, vm_status, events_count: (.events | length)}'

List Recent Transactions

# List the 5 most recent transactions
curl -s "https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions?limit=5" \
  -H "Accept: application/json" | jq '.[] | {version, hash: .hash[0:16], type: .type, success}'

# List transactions starting from a specific version
curl -s "https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1/transactions?start=125304890&limit=10" \
  -H "Accept: application/json" | jq '.[].version'

Error Handling

Common Error Responses

Handling Sequence Number Conflicts

from aptos_sdk.client import RestClient

client = RestClient("https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1")

def submit_with_retry(sender, payload, max_retries=3):
    """Submit a transaction with automatic sequence number refresh on conflict."""
    for attempt in range(max_retries):
        try:
            tx_hash = client.submit_transaction(sender, payload)
            return client.wait_for_transaction(tx_hash)
        except Exception as e:
            if "sequence_number" in str(e).lower() and attempt < max_retries - 1:
                # Refresh the account's sequence number and retry
                print(f"Sequence number conflict, retrying (attempt {attempt + 2})")
                continue
            raise

Common Use Cases

Token Transfers

The most basic transaction type. Transfer MOVE or any fungible token between accounts using 0x1::coin::transfer or 0x1::aptos_account::transfer.

Smart Contract Interaction

Call any entry function on a published Move module. This covers DeFi operations (swaps, deposits, borrowing), NFT minting, governance voting, and all other on-chain actions.

Module Publishing

Deploy new Move modules to your account using the module bundle payload type. This is how smart contracts are published on Movement.

Movement-Specific Notes

• Fast finality -- Transactions confirm in 1-3 seconds on Movement. Set polling intervals accordingly.
• BCS encoding -- Always prefer BCS-encoded submissions in production. JSON submission works but is less efficient and requires pre-computed signatures.
• Gas estimation -- Use the simulation endpoint to estimate gas before submitting. Movement gas prices are typically lower than Ethereum L1 but vary with network load.
• Expiration -- Set expiration_timestamp_secs to 30-60 seconds in the future. With fast finality, transactions that do not execute within seconds likely have issues.

Related Endpoints

• POST /v1/transactions/simulate -- Simulate a transaction to preview gas costs and execution result.
• GET /v1/accounts/{address} -- Get the current sequence number for the sender account.
• GET /v1/accounts/{address}/events/{creation_number} -- Query events emitted by transactions.
• POST /v1/view -- Read on-chain state without submitting a transaction.