Skip to content

Transaction Descriptions ​

Give the API a Sui transaction. You get back one short summary and an ordered list of the actions in it, each with the protocol, the amounts and the commands it came from.

text
Swapped 8.0761 SUI for 391,158.614 SUIDOG on Cetus

Use it for wallet history, explorer list rows, bots and alerts. You do not need your own decoders for each protocol.

Early access: The response format can change before general availability. Check the version field to see when a description changed.

Authentication ​

Send an API key with the data scope in the x-api-key header. The network follows the project of the key.

NetworkBase URL
Mainnethttps://mainnet-api.inodra.com
Testnethttps://testnet-api.inodra.com

Endpoints ​

EndpointUseCredits
GET /v1/transactions/{digest}/descriptionDescribe one transaction2
POST /v1/transactions/descriptionsDescribe up to 50 transactions2 per digest
POST /v1/transactions/describeDescribe a transaction before it runs5

Describe a transaction ​

bash
curl https://mainnet-api.inodra.com/v1/transactions/6LkURRnPfcDXnMXvvh11HAPc1k4HzRWnwS7FbPeui3rG/description \
  -H "x-api-key: indr_pat_..."

Query parameters:

ParameterDescription
addressWrite transfer sentences from this address. The recipient sees Received 1.5 SUI from 0xa1b2…c3d4.
commandReturn only this command and its actions. summary still covers the whole transaction.

Describe many transactions ​

For a list of transactions, for example an address history page:

bash
curl https://mainnet-api.inodra.com/v1/transactions/descriptions \
  -H "x-api-key: indr_pat_..." \
  -H "content-type: application/json" \
  -d '{"digests": ["6LkURRnPfcDXnMXvvh11HAPc1k4HzRWnwS7FbPeui3rG", "F7fHmNEqUGSoC7GVoijbCfiG74jDC11ZoNxNqzK4bm7r"]}'

The data array is in the order of digests. A transaction that is not found is null. If a transaction could not be described this time (an upstream error), it is also null and its index is in failed. Retry those. Every digest in the request is billed, also a failed one.

Describe a transaction before it runs ​

Send the unsigned transaction bytes. The API simulates them and describes the result. Nothing is executed. Use it to show the user what a transaction will do before they sign.

ts
import { ChannelCredentials } from '@grpc/grpc-js'
import { SuiGrpcClient } from '@mysten/sui/grpc'
import { Transaction } from '@mysten/sui/transactions'
import { GrpcTransport } from '@protobuf-ts/grpc-transport'

const transport = new GrpcTransport({
  host: 'mainnet-grpc.inodra.com:443',
  channelCredentials: ChannelCredentials.createSsl(),
  meta: { 'x-api-key': process.env.INODRA_API_KEY! }
})
const client = new SuiGrpcClient({ network: 'mainnet', transport })

const tx = new Transaction()
tx.setSender('0xYOUR_ADDRESS')
const [coin] = tx.splitCoins(tx.gas, [1_000_000_000])
tx.transferObjects([coin], '0xRECIPIENT')
const bytes = await tx.build({ client })

const res = await fetch('https://mainnet-api.inodra.com/v1/transactions/describe', {
  method: 'POST',
  headers: { 'x-api-key': process.env.INODRA_API_KEY!, 'content-type': 'application/json' },
  body: JSON.stringify({ transaction: Buffer.from(bytes).toString('base64') })
})
const { data } = await res.json()
console.log(data.summary) // Sent 1 SUI to 0xreci…ient

The response has "simulated": true.

Response ​

json
{
  "data": {
    "digest": "6LkURRnPfcDXnMXvvh11HAPc1k4HzRWnwS7FbPeui3rG",
    "sender": "0x78c7…a884",
    "status": "success",
    "summary": "Swapped 8.0761 SUI for 391,158.614 SUIDOG on Cetus",
    "failure": null,
    "actions": [
      {
        "index": 0,
        "kind": "swap",
        "protocol": { "id": "cetus", "name": "Cetus" },
        "sentence": "Swapped 8.0761 SUI for 391,158.614 SUIDOG on Cetus",
        "commands": [1],
        "commandsExact": true,
        "fields": {
          "in": {
            "type": "amount",
            "coinType": "0x0000…0002::sui::SUI",
            "symbol": "SUI",
            "decimals": 9,
            "raw": "8076146671",
            "value": "8.076146671",
            "display": "8.0761"
          },
          "out": { "type": "amount", "symbol": "SUIDOG", "raw": "391158613961300", "...": "..." },
          "pool": { "type": "object", "value": "0xcb9d…6852" }
        },
        "tier": "catalog",
        "source": {
          "kind": "event",
          "rule": "cetus/swap",
          "ruleVersion": 1,
          "events": [0],
          "eventTypes": ["0x1eab…b2fb::pool::SwapEvent"],
          "function": null
        },
        "includes": 0
      }
    ],
    "commands": [
      { "index": 0, "kind": "SplitCoins", "sentence": "Split off 1 coin", "actions": [] },
      {
        "index": 1,
        "kind": "MoveCall",
        "function": "0x89a0…d4b1::cetus::swap_b2a",
        "sentence": "Called cetus::swap_b2a in package 0x89a0…d4b1",
        "actions": [0]
      },
      {
        "index": 2,
        "kind": "TransferObjects",
        "sentence": "Transferred 1 object to 0x78c7…a884",
        "actions": []
      }
    ],
    "gas": {
      "owner": "0x78c7…a884",
      "sponsored": false,
      "fee": { "symbol": "SUI", "value": "0.001453599", "...": "..." }
    },
    "coverage": "catalog",
    "version": { "engine": "1.0.0", "catalog": "2026-11-12.1" },
    "simulated": false
  }
}

Fields ​

FieldDescription
summaryOne line for a list row. One action gives its sentence. Two actions are joined. More give the main action and and N more actions.
failureFor a failed transaction: a sentence, the error message, the failed command and the abort location (package, module, function, code).
actionsWhat happened, in the order it happened. Use sentence for display and fields for your own text or logic.
commandsEvery command of the transaction with a short sentence and the actions it is linked to.
coveragecatalog when a protocol rule described the transaction, generic when only balance or object changes did, none when nothing was found.
versionThe engine and catalog versions. When one changes, a description can change too.

Actions ​

  • kind is a fixed word, for example swap, transfer, stake, unstake, supply, withdraw, borrow, repay, claim, order_place, order_cancel, nft_buy, name_register, oracle_update, bridge, crank (work done for other users, such as settlement). Generic actions use exchange, receive, spend, create, publish, upgrade and call; a catalog rule can also use create.
  • Every amount has raw (the integer on chain), decimals, value (exact) and display (the rounded text in the sentence). When a coin has no metadata, decimals is null and value is the raw integer.
  • source.rule names the catalog rule, for example cetus/swap. It is null for generic actions. engine/route is a swap route the engine joined from several steps.
  • includes counts the events or route steps merged into the action.

Commands and events ​

Sui events do not say which command emitted them, only the package and module of the command. The API links each event to the commands that called that module, in order. When more than one command can be the source, commandsExact is false and commands lists every candidate.

Tiers ​

  1. Catalog: rules for known protocols, matched on event types. See Description Catalog.
  2. Generic: the sender's balance changes (gas removed) and object changes. These sentences say what moved, not why. A lending deposit and a swap can look the same here, so the text stays neutral: Paid 2 SUI and received 5 USDC.
  3. Failure: a failed transaction has no events. The sentence names the abort location, for example Failed: router::swap in Cetus stopped with code 1.

A swap route is only joined into one action when the sender's balances show the start coin going down and the end coin going up. Then the amounts come from those balances. Otherwise the steps stay separate.

Errors ​

StatusCodeWhen
400VALIDATION_FAILEDThe digest, address or body is not valid
400INVALID_COMMANDcommand is not a command of the transaction
400INVALID_TRANSACTIONThe node cannot read the transaction bytes
404NOT_FOUNDThe transaction does not exist on this network

Notes ​

  • Descriptions of executed transactions are cached. A transaction does not change, so the cache only refreshes when the engine or the catalog version changes.
  • No USD values are given.
  • Addresses in sentences are short. The full address is in fields.
  • Symbols come from on-chain coin metadata, and anyone can publish a coin called USDC. Check coinType before you trust a symbol, for example in a signing preview.
  • gas.fee is computation plus storage minus the storage rebate, so it can be negative.
  • A failed transaction has coverage: "generic" unless a call rule wrote an intent sentence; its sentence is in summary and failure.
  • A batch is priced per digest, also when the same digest is in it twice.

The full-stack Sui data layer.