Command line

cardano-swap is the operator, deployment, audit and measurement tool. It quotes, builds, signs and submits, and it reconstructs what the product did on chain from public data.

Invocation

After pnpm build, run it through Node:

node apps/cli/dist/main.js help

The package declares the binary name cardano-swap, so a linked install runs:

cardano-swap help

Both forms are used interchangeably below.

Every command requires a network

cardano-swap tip --network preprod

There is no default. --network takes mainnet, preprod or preview, and CARDANO_SWAP_NETWORK in the environment is read when the flag is absent. integrity is the one command that needs no network, because it reads the repository rather than a chain.

Amounts are base units

--amount is always in base units. An asset whose decimal count nobody has declared is printed in base units and labelled, rather than scaled by a guess.

Commands

wallet create

Creates the operator wallet for a network and writes it with owner-only permissions, mode 600. Refuses to overwrite an existing wallet unless --overwrite is passed.

Prints the address, the reward address, and where the file was written.

cardano-swap wallet create --network preprod

wallet show

Prints the operator address, its UTxO count, its ADA balance and every native asset it holds.

Exits 1 when no operator wallet exists for the network.

config show

Prints the resolved configuration for a network as JSON, after schema validation and fingerprint recomputation.

tip

Prints the chain tip and the live protocol parameters: provider name, epoch, block height, slot, block hash, maximum transaction size, maximum execution memory and steps, and the reference script cost per byte.

assets

Lists every registered asset for the network with its policy id and asset name, decimal count, the source of that decimal count, and whether it is a verified stablecoin.

pools

Discovers and summarises every pool of every enabled venue. Prints the block the read was stamped at, the total pool count, a count per venue, and every venue that was skipped with its reason.

quote

Quotes a swap and prints the full quote.

cardano-swap quote --network mainnet --in USDCx --out USDM --amount 10000000000

The output carries the pair, the network and block, what you pay and receive, the rate, the minimum on chain with its slippage, the price impact, the four fee lines, the route with its atomicity and per branch hops, the saving against the direct route, and every warning.

The shape of the output, with the field names it prints:

pair            <in> -> <out>
network         <network> at block <height>
you pay         <amount> <in>
you receive     <amount> <out>
rate            <rate> <out> per <in>
minimum on chain <amount> <out>  (<n> bps slippage)
price impact    <n> %

fees
  pool fee              <amount> <in>
  venue protocol fee    <amount> <in>
  venue execution       <amount> ADA
  refundable deposit    <amount> ADA

route
  settles as      atomic | single-order | needs-settlement
  venues          <venue ids>
  branch 1        <amount> in -> <amount> out
    <venue id> <poolTxHash#index>

saving against the direct route
  baseline        <amount> <out> on <venue id>
  baseline pool   <poolTxHash#index>
  saving          <amount> <out> (<n> bps)
  beats direct    yes | no

what you should know
  - <warning>

When no direct pool exists, the saving block prints none: followed by the reason instead of the four lines above.

swap

Quotes, then builds and signs a swap that settles in the transaction you sign. Add --submit to send it.

cardano-swap swap --network preprod \
  --in fUSDM --out fUSDA --amount 5000000 --atomic --submit

Takes the same flags as quote, plus --submit.

This command executes routes whose atomicity is atomic. A route that settles as anything else is reported with its atomicity and exits 1. Use order place for a Commitment class route.

Without --submit it prints the transaction size and pool leg count, signs, and stops. That is the whole build and sign path, exercised without spending anything.

With --submit it prints the submitted transaction hash, waits for confirmation, and prints the confirmation result.

orders

Lists every order still resting for the operator address on this network.

order place

Quotes a Commitment class route, then builds and signs the order. Add --submit to send it.

cardano-swap order place --network preprod \
  --in ADA --out tiUSD --amount 30000000 --submit

The quote is restricted to Commitment class venues, because a Kernel route would settle inside your own transaction and needs no order at all.

--min-out can only tighten the bound. The builder refuses anything looser than the quote.

After building it prints the signer, the order script address, what is paid in, the minimum, the batcher fee offered and the deposit returned on fill, the expiry as an ISO timestamp, the transaction size, and the CIP-20 tag read back out of the finished transaction bytes.

order cancel

Builds and signs the cancellation of one order, returning its funds to the address the datum names.

cardano-swap order cancel --network preprod --order <TXHASH>#<INDEX> --submit

--order TXHASH#INDEX is required. Prints what is cancelled, where the funds return, the exact value returned, the transaction size and the tag.

audit

Reconstructs every swap this product made, from chain data alone.

cardano-swap audit --network preprod --limit 200

--limit defaults to 200 and bounds the newest-first window over the Kernel venue's pool script.

Two runs against the same chain state produce identical output. See Reproducing the saving claim.

measure

Counts this product's own declared footprint on chain and proves script provenance.

cardano-swap measure --network preprod

--limit sets the per venue scan window. See Footprint and measurement.

footprint build

Writes footprint.<network>.json declaring the on-chain identifiers: every script this project deployed, the asset policies it moves, the message tag, the operator wallets by stake key, and the third party venues it routes across.

Prints a count for each section. When no script of this project is deployed on the network, it says so rather than declaring an empty entry as though it were a value.

footprint check

Resolves every entry of the declared footprint on chain and prints one line per entry, ok or FAIL, with the detail. Exits 1 if any entry fails to resolve.

integrity

Scans the repository source and proves no reward, rebate, points, referral or fee sponsoring code path exists.

cardano-swap integrity

Needs no network. It runs against the current working directory.

Prints the number of files scanned, the number of times a banned concept appears inside a comment, which is the rule being stated rather than broken, and the number of violations in code. Exits 1 when any violation is found.

deploy show

Prints the compiled validators from onchain/plutus.json: the blueprint title and Plutus version, then each validator's title, hash, compiled size and the enterprise address it would deploy to on this network. Finishes with the settlement hash the configuration currently records, or not deployed.

deploy settlement

Publishes the settlement validator as a reference script.

cardano-swap deploy settlement --network preprod --submit

Without --submit it is a dry run: it prints the size and hash it would publish and stops.

With --submit it deploys and prints the script hash, script address, reference UTxO, transaction hash and size, followed by the configuration keys to write those values into.

--allow-mainnet is required to load the operator wallet on mainnet. Every routine operation in this tool runs on a test network, so a mainnet deployment is a deliberate act.

Global options

Environment variables

See Configuration reference.

Related