API Reference

Supra provides APIs for interacting with automation services, monitoring execution, and retrieving registry data. The sections below cover the on-chain registry module, the REST endpoints, and the error codes and events the registry defines.

All amounts are in quants (1 SUPRA = 100,000,000 quants). Governance can change the registry parameters, such as the cycle duration, the gas capacity and the fee parameters. Read them from the chain as shown in Calculate task-expiry-time & task-automation-fee.

Automation Registry Move Module

The on-chain module 0x1::automation_registry provides the following APIs.

Registration

Users cannot call the register() function directly. Instead, a task is registered by submitting a signed transaction whose payload is of type AutomationRegistration. The payload wraps the target entry function, its arguments and the registration parameters. The Supra CLI builds and submits this transaction. The registry validates the task and accepts it according to the submitted parameters and network rules.

Example: Registering a Task Using Supra CLI

supra move automation register \
  --task-max-gas-amount <MAX_GAS> \
  --task-gas-price-cap <GAS_PRICE_CAP> \
  --task-expiry-time-secs <EXPIRY> \
  --task-automation-fee-cap <FEE_CAP> \
  --function-id "<ADDRESS>::<MODULE>::<FUNCTION>" \
  --args address:<RECIPIENT> u64:<AMOUNT> \
  --rpc-url <RPC_URL>

Derive each placeholder as follows:

This command builds the registration transaction for the specified function with the given arguments. It does not call register() directly. The registration fee (flat_registration_fee_in_quants) and a deposit equal to <FEE_CAP> are taken from the account when the transaction executes. See Fee Structure for when the deposit is refunded.

To simulate task creation without submission, add --simulate:

supra move automation register --simulate ...

Cancellation

public entry fun cancel_task(owner_signer: &signer, task_index: u64)

This function cancels the task with the given index. A pending task is removed at once. An active task stays scheduled until the current cycle ends and is removed at the next cycle boundary.

public entry fun stop_tasks(owner_signer: &signer, task_indexes: vector<u64>)

This function stops the listed tasks immediately and refunds part of the fees. The CLI equivalents are supra move automation cancel and supra move automation stop-tasks. See Canceling Your Automation Task.

Read Functions

The functions below are view functions. Call them with supra move tool view:

supra move tool view \
  --function-id 0x1::automation_registry::<FUNCTION> \
  --args <TYPE>:<VALUE> \
  --rpc-url <RPC_URL>

or with a POST request to <RPC_URL>/rpc/v3/view:

curl -X POST <RPC_URL>/rpc/v3/view \
  -H 'content-type: application/json' \
  -d '{"function": "0x1::automation_registry::<FUNCTION>", "type_arguments": [], "arguments": [<ARGUMENTS>]}'

Omit --args for functions without parameters. Pass u64 arguments as strings in the REST body.

get_epoch_locked_balance and get_gas_committed_for_*_epoch keep their names from before cycles were introduced; they refer to cycles.

Devnet also provides register_without_validation and register_system_task_without_validation, which let a smart contract register a task. They require the supra_automation_v2_1 feature, abort with EDISABLED_AUTOMATION_V2_1_FEATURE when it is off, and do not validate the payload. They are not available on Mainnet and Testnet.

The diagram below shows the API architecture map.

REST API Endpoints

Supra exposes these REST endpoints for tracking automation activity:

Error Codes and Fee Events

Error Codes

The registry aborts with named error codes when a task fails validation. The codes most relevant to registration and cancellation are:

A registration from an account with too little SUPRA fails in the coin transfer, not with an automation error code.

These codes are visible in the status of a failed transaction and are useful for debugging or monitoring failed submissions.

Fee and Registry Events

These events are emitted by the registry module and are indexed for external observability:

A task removed for an insufficient balance does not receive its deposit back.

On Devnet, the registry also emits TaskCancelledByRuntime when the runtime cancels a task that registered without payload validation and turned out to be invalid. Its diagnostic_message field gives the reason.

Registry API Overview

The Automation Registry is a native on-chain module that stores all registered tasks. This registry controls task lifecycle, execution ordering, and expiry/cancellation management. Automation tasks are treated as internal transactions. These are executed directly by the blockchain’s validator layer.

This diagram gives an overview of the interaction of the registry system.

Registration Parameters

The registration transaction carries these parameters:

The registry also stores tx_hash, the hash of the registration transaction, and aux_data, which holds the task type and its priority.

Task Metadata Structure

get_task_details returns an AutomationTaskMetaData with these fields:

• task_index and owner
• payload_tx: the encoded entry function call
• expiry_time and registration_time, in seconds
• max_gas_amount, gas_price_cap and automation_fee_cap_for_epoch
• locked_fee_for_next_epoch: the deposit locked for the task
• tx_hash and aux_data
• state: 0 for pending, 1 for active, 2 for cancelled

Fee Structure

Flat Registration Fee

Paid once during registration. Non-refundable.

Deposit

At registration, the account also locks a deposit equal to the automation fee cap. It is returned in full when an active task expires, is cancelled or stopped, or is removed because its fee for a cycle exceeds the cap, and for every task when governance suspends automation. Cancelling or stopping a pending task returns half of it. A task removed because the owner’s balance cannot cover a cycle’s fee does not get it back. The deposit does not pay cycle fees.

Automation Fee (Per Cycle)

Charged from the account balance at the start of each cycle in which the task is active, based on:

• The task’s max gas
• The registry’s congestion level
• The length of the cycle, or the time the task remains active in the cycle if that is shorter. A task that is new in a cycle is always charged for the full cycle.

The fee is:

fee = (automation_base_fee_in_quants_per_sec + congestion_fee_per_sec) * duration_secs * max_gas_amount / registry_max_gas_cap

Both per-second rates are for the full registry capacity, and the task pays the share max_gas_amount / registry_max_gas_cap.

• congestion_fee_per_sec is computed from the gas committed for the next cycle plus the task’s own gas, so the task’s own gas can raise it.
• estimate_automation_fee divides by the next cycle’s cap, get_next_epoch_registry_max_gas_cap. The charge at a cycle boundary uses the active registry_max_gas_cap.
• duration_secs is the cycle length, except that an active task whose expiry falls inside the cycle pays for expiry - now.

Call estimate_automation_fee with a gas amount to get the fee for that amount.

Congestion Fee

The congestion fee applies when the gas committed by tasks exceeds congestion_threshold_percentage of the registry’s maximum gas cap. It equals congestion_base_fee_in_quants_per_sec * ((1 + s) ^ congestion_exponent - 1) per second, for the full registry capacity, where s is the fraction of the registry capacity above the threshold. The fee estimate uses the next cycle’s cap, get_next_epoch_registry_max_gas_cap. The charge at a cycle boundary uses the active registry_max_gas_cap.

Refunds

Part of a cycle fee is refunded in two cases:

• Suspension. When governance suspends automation during a cycle, each active task is refunded the fee for the rest of the cycle, in proportion to the time left, and every task is refunded its deposit in full. A suspension at a cycle boundary, before the next cycle’s fees are charged, refunds only the deposits.
• stop_tasks. An active or cancelled task is refunded half of the fee for the rest of the cycle, and its deposit in full. A pending task is refunded half of its deposit.

Cancelling a task with cancel_task, or letting it expire, refunds no part of the current cycle’s fee.

Events

The registry emits events on:

• Task registration
• Fee withdrawals and refunds
• Cancellations and stops
• Removal of tasks at a cycle transition
• Registry configuration changes