GasFree Trace Status

API-v2gasless::trace_status

gasless::trace_status

Returns the current status of a submitted TRON GasFree (gasless) TRC20 transfer, identified by the trace_id returned from send_raw_transaction when the gasless transfer was submitted.

This is a one-off poll. To receive live updates as the transfer progresses, use stream::gasless_trace::enable instead.

Request Parameters

Parameter	Type	Description
coin	string	The TRON GasFree TRC20 token the transfer belongs to. Must be activated with a GasFree provider.
trace_id	string	The transfer's tracking id, returned by `send_raw_transaction` when the gasless transfer was submitted.

Response Parameters

Parameter	Type	Description
state	string	Lifecycle state of the transfer. One of `pending`, `submitted`, `on_chain`, `confirmed`, or `failed`. `confirmed` and `failed` are terminal.
tx_hash_on_chain	string	Optional. On-chain transaction hash, present once the transfer reaches the `on_chain` state.
block_height	integer	Optional. Block height the transfer was included in, once on chain.
confirmed_at	integer	Optional. Unix timestamp (seconds) of block inclusion, once on chain.
final_fee	string (numeric)	Optional. Total fee charged in the token, available once the transfer is on chain.
failure_reason	string	Optional. Reason for failure, present only when `state` is `failed`.

📌 Examples

POST

gasless::trace_status

{
  "mmrpc": "2.0",
  "userpass": "RPC_UserP@SSW0RD",
  "method": "gasless::trace_status",
  "params": {
    "coin": "USDT-TRC20",
    "trace_id": "6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0"
  },
  "id": 0
}

Response (on chain, confirmed)

{
  "mmrpc": "2.0",
  "result": {
    "state": "confirmed",
    "tx_hash_on_chain": "2222222222222222222222222222222222222222222222222222222222222222",
    "block_height": 57175988,
    "confirmed_at": 1747909638,
    "final_fee": "2.000000",
    "failure_reason": null
  },
  "id": 0
}

Response (still in progress)

{
  "mmrpc": "2.0",
  "result": {
    "state": "submitted",
    "tx_hash_on_chain": null,
    "block_height": null,
    "confirmed_at": null,
    "final_fee": null,
    "failure_reason": null
  },
  "id": 0
}

Error Types

Error Type	Description
CoinNotFound	The specified coin was not found or is not activated.
NotEthCoin	The specified coin is not an EVM/TRON coin.
CoinNotSupported	The coin does not support GasFree trace status (only TRON GasFree TRC20 tokens do).
GaslessNotConfigured	The coin has no GasFree provider configured.
TraceNotFound	No transfer was found for the given `trace_id`.
InvalidTraceId	The `trace_id` is malformed.
ProviderError	The GasFree provider returned an error.
InternalError	An internal error occurred.

Error (Trace Not Found)

{
    "mmrpc": "2.0",
    "error": "Trace '6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0' not found",
    "error_path": "gasless",
    "error_trace": "gasless:88]",
    "error_type": "TraceNotFound",
    "error_data": "6c3ff67e-0bf4-4c09-91ca-0c7c254b01a0",
    "id": 0
}

Error (Gasless Not Configured)

{
    "mmrpc": "2.0",
    "error": "Coin 'USDT-TRC20' has no GasFree provider configured",
    "error_path": "gasless",
    "error_trace": "gasless:80]",
    "error_type": "GaslessNotConfigured",
    "error_data": "USDT-TRC20",
    "id": 0
}

On this page

GasFree Trace Status