Actions

Actions are the JSON layer over SugarClient. The aero CLI flags, the TUI forms and the headless sugar-ts parser all turn their input into the same action request. Transaction actions return unsigned plans here too. Nothing is signed.

Run an action#

import { executeSugarAction, executeSugarActionJson } from '@beegreat/sugar'

const pools = await executeSugarAction('pools', {
  chain: 8453,
  pool_type: 'cl',
  limit: 5,
})

const text = await executeSugarActionJson('quote', {
  chain: 8453,
  from_token: 'ETH',
  to_token: 'USDC',
  amount: '0.01',
  use_decimals: true,
})

executeSugarAction(action, parameters, options?) validates the parameters, creates a SugarClient for parameters.chain, runs the action and resolves to SugarJson, plain JSON in which every bigint is a decimal string. executeSugarActionJson resolves to the same value as a string indented by two spaces.

options takes every client option, such as rpcUrl, rpcPolicy or cacheStore, plus clientFactory(chainId, options) to supply your own client. A wallet parameter becomes the client's account.

Validation failures and domain errors, such as a missing token or an empty route, reject with an Error. RPC failures reject with a SugarRpcError, described in Configuration.

Action names#

There are 17 actions. SUGAR_ACTIONS lists all of them and isSugarAction(name) checks a string. The 11 transaction actions are listed in SUGAR_TX_ACTIONS, exported with isSugarTxAction from @beegreat/sugar/contracts.

Every action also takes chain, and transaction actions take wallet. The top-level aero commands use the same names with dashes, such as claim-emissions. The stock actions live under aero stocks and aero index. See the CLI reference.

Parameters#

ACTION_SCHEMA, defined in action-schema.ts, is the single description of every action's parameters. CLI flags and help, TUI forms, headless flag parsing and validateSugarRequest are all derived from it, so it is always current. Read it at runtime with requestParameters(action), which adds the chain and wallet context parameters.

import { requestParameters } from '@beegreat/sugar'

for (const spec of requestParameters('swap')) {
  console.log(spec.name, spec.kind, spec.required ?? false, spec.description)
}

Amounts#

For quote, swap, deposit and create_venft, amounts are raw integer strings in the token's smallest unit unless use_decimals is true. amount: '0.01' without use_decimals fails, because 0.01 is not an integer. Pass amount and amount0 as strings, not numbers.

Selecting a position#

withdraw, stake, unstake, claim_emissions and claim_fees need position, pool, or both. With only position, the client scans every pool for that NFT. With only pool, the wallet must hold exactly one position in it. Basic pool positions have ID 0, so select them by pool.

Validation#

validateSugarRequest(action, raw) returns the cleaned parameters or throws an Error with a readable message. executeSugarAction calls it first. Call it yourself to reject bad input early, for example at an API boundary.

import { validateSugarRequest } from '@beegreat/sugar'

const parameters = validateSugarRequest('swap', {
  chain: 8453,
  wallet: '0xYOUR_ADDRESS',
  from_token: 'ETH',
  to_token: 'USDC',
  amount: '0.01',
  use_decimals: true,
})

It enforces these rules.

• Unknown parameter names are rejected, for example Unsupported parameter for swap: private_key.
• Every value must match its kind. null and undefined values are dropped.
• Required parameters must be present.
• chain must be supported, limit must be 1 to 100, offset at least 0, slippage 0 to 1, fraction above 0 and at most 1, deadline_minutes positive, and lock_duration_seconds a positive safe integer.
• positions needs wallet or owner. Position actions need pool or position.
• deposit takes either pool or a new pool description, never both. A new pool needs token0, token1 and pool_type, plus tick_spacing when the type is cl. tick_spacing is rejected for other types.
• Addresses must be 20-byte 0x hex. Strings are limited to 256 characters, and a string shaped like a 32-byte private key is rejected with Sugar accepts public addresses only, never private keys.

Output#

Reads#

type_label is volatile, stable or cl- followed by the tick spacing. In quote, the prices come from the oracle in the chain's stable token and price_impact compares the output with the oracle rate. Both are null when the oracle cannot price a token.

Transaction plans#

Every transaction action returns an object with two lists.

• transactions is the ordered list of unsigned transactions, with value as a decimal string.
• transaction_steps holds the same transactions as { role, transaction }. role is action for the last entry and approval for every entry before it.

Each action adds one context object.

Show the context to whoever signs, especially min_amount_out for swaps and minimum for stock trades.

Headless CLI helpers#

@beegreat/sugar/cli turns argv-style input into the same requests and always prints JSON. parseSugarCliArgs(argv) accepts --flag=value, --flag value, bare boolean flags and --no-<flag> for booleans. runSugarCli(argv, options?, write?) parses, runs the action and writes the JSON.

import { runSugarCli } from '@beegreat/sugar/cli'

await runSugarCli(['pools', '--chain=8453', '--pool-type=cl', '--limit=5'])

When tsc checks a project that imports @beegreat/sugar/cli, it also checks the TUI source behind it. Add @types/react as a dev dependency and set these compiler options, or the check fails inside the package.

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@opentui/react"
  }
}