Skip to main content
Multi-party exchanges of HBAR, fungible HTS tokens, and NFT serials, composed step by step locally and executed as one Hedera transfer transaction (CryptoTransfer). If the submission fails (for example insufficient balance), the saved swap stays in CLI state unless you swap delete it.
Swaps are stateful: nothing is submitted until hcli swap execute. Inspecting local drafts does not hit the network. Use swap list, swap view, and hcli swap --help on your installed build.

Typical workflow

Create a named swap, add each transfer you want, review, then execute
Drop a draft without submitting

Limits and behaviour

  • Transfer entry cap: A single Hedera TransferTransaction supports at most 10 transfer entries. The CLI uses the same limit when you add steps.
  • HBAR and FT: Each add-hbar or add-ft step counts as one entry.
  • NFTs: Each serial in add-nft --serials counts as one entry when capacity is checked for that command.
  • Atomicity: All entries are applied in one transaction — they succeed or fail together.
On swap execute, every distinct source account (--from, operator by default) must be able to sign. The CLI collects the required keys when signing before submission. After a successful execute, that swap name is removed from CLI state automatically.

State storage

Draft swaps persist under your CLI state directory (see Overview), typically ~/.hiero-cli/state/swap-storage.json, per network.

Full command reference

Create an empty swap with a memo stored for the eventual transaction (optional). No ledger transaction is sent.
string
required
Name for this swap (used with all other swap subcommands).
string
Optional memo on the swap execute transaction.
Example
Append an HBAR transfer from --from (default: operator) to --to.
string
required
Swap name.
string
required
Destination account (account ID or alias).
string
required
Amount: plain value is in HBAR (for example 10). The suffix t means tinybars (for example 1000t).
string
Source account: accountId:privateKey, alias, account ID, or key reference. Defaults to the operator.
string(local|local_encrypted)
Key manager for resolving credentials (defaults to config).
Examples
Append a fungible HTS transfer. For display amounts (without t), decimals are resolved from the mirror node when you run the command.
string
required
Swap name.
string
required
Destination account.
string
required
Fungible token ID or imported alias.
string
required
Amount in display units unless you append t for base units (consistent with other token commands).
string
Source account (defaults to operator).
string(local|local_encrypted)
Key manager (defaults to config).
Examples
Append one or more NFT serial transfers (same token, comma-separated serials).
string
required
Swap name.
string
required
Destination account.
string
required
NFT token ID or imported alias.
string
required
Comma-separated serial numbers (for example 1,2,3).
string
Source account (defaults to operator).
string(local|local_encrypted)
Key manager (defaults to config).
Examples
Build the TransferTransaction, sign with every required from key, submit, and on success delete the swap from state.
string
required
Swap to execute (must contain at least one transfer).
Example
Summaries for all swaps stored for the current network (names, transfer counts, limits).Example
Full detail for one named swap stored in CLI state: memo, transfers (type HBAR / FT / NFT), from/to, and counts versus the protocol limit (10 entries per transaction).Example
Remove the named swap from state without submitting a transaction.
string
required
Swap to delete.
Example
  • Hedera semantics for moving value between several accounts in one transaction match the topic covered under Atomic swaps in the SDK documentation.
  • The Batch plugin queues distinct inner transactions for HIP-551 atomic batch submission. swap assembles one CryptoTransfer. Use whichever matches your operational model.