Transaction Signing

The CLI can sign Cardano transactions locally using a .skey file and submit them directly to the network. The API builds the transaction, you sign it with your key, and submit it — no browser wallet required.

The workflow uses four composable commands:

tx build → tx sign → tx submit → tx register

Each command supports --output json and can be piped together for scripting.

Prerequisites

• User authentication (wallet login) for tx build and tx register
• A Cardano .skey file (payment signing key from cardano-cli)
• A Cardano submit API URL (Blockfrost, Maestro, or self-hosted)

Setup

Configure your submit API URL once:

andamio config set-submit-url https://cardano-mainnet.blockfrost.io/api/tx/submit

This is stored in ~/.andamio/config.json. You can also pass --submit-url per command or set the ANDAMIO_SUBMIT_URL environment variable.

The Four Steps

1. Build an Unsigned Transaction

Request an unsigned transaction from the Andamio API:

andamio tx build /v2/tx/global/user/access-token/mint \
  --body '{"alias":"dev1","initiator_data":"addr_test1..."}' \
  --output json

The API builds the transaction (handles UTxO selection, fee calculation, script logic) and returns the unsigned CBOR:

{ "unsigned_tx": "84a400..." }

Some endpoints return additional fields like course_id or project_id — these are passed through in the response.

Use --body-file for complex request bodies:

andamio tx build /v2/tx/instance/owner/course/create \
  --body-file create-course.json \
  --output json

To see all available transaction endpoints:

andamio spec paths --filter tx

2. Sign Locally

Sign the unsigned transaction with your .skey file:

andamio tx sign --tx 84a400... --skey ./payment.skey --output json

Returns the signed transaction and its hash:

{ "signed_tx": "84a400...", "tx_hash": "abc123..." }

This is a purely local operation — no network calls. Your private key never leaves your machine.

For large transactions, use a file:

andamio tx sign --tx-file unsigned.cbor --skey ./payment.skey --output json

3. Submit to the Network

Submit the signed transaction to the Cardano network:

andamio tx submit --tx 84a400... --output json

If you configured a submit URL (step 0), it uses that. Otherwise pass it explicitly:

andamio tx submit --tx 84a400... \
  --submit-url https://cardano-mainnet.blockfrost.io/api/tx/submit \
  --submit-header "project_id: your-blockfrost-project-id" \
  --output json

--submit-header is repeatable for providers that require authentication headers.

4. Register for Tracking

Register the transaction hash with Andamio so the platform can track its confirmation:

andamio tx register --tx-hash abc123... --tx-type access_token_mint

For transaction types that create new resources, pass the ID returned by tx build:

andamio tx register --tx-hash abc123... --tx-type course_create --instance-id <course-id>

Check confirmation status:

andamio tx status abc123...

One-Command Pipeline: tx run

For the common case of build → sign → submit → register → poll, use tx run to execute the full lifecycle in one command:

andamio tx run /v2/tx/global/user/access-token/mint \
  --body '{"alias":"dev1","initiator_data":"addr_test1..."}' \
  --skey ./payment.skey \
  --tx-type access_token_mint

This:

1. Builds the unsigned transaction via the API
2. Signs it locally with your .skey
3. Submits to the Cardano network
4. Registers the tx hash for tracking
5. Polls for confirmation (unless --no-wait)

Optional flags:

• --body-file for complex request bodies
• --no-wait to skip polling after submission
• --timeout to set polling timeout (default: 5 minutes)
• --metadata for additional registration metadata
• --instance-id for resource creation transactions (course_create, project_create)

# Create a course on-chain
andamio tx run /v2/tx/instance/owner/course/create \
  --body-file create-course.json \
  --skey ./payment.skey \
  --tx-type course_create \
  --instance-id <course-id>

Scripting the Full Pipeline

Chain all four steps together with jq:

# 1. Build
RESULT=$(andamio tx build /v2/tx/global/user/access-token/mint \
  --body '{"alias":"dev1","initiator_data":"addr_test1..."}' \
  --output json)
UNSIGNED_TX=$(echo "$RESULT" | jq -r '.unsigned_tx')

# 2. Sign
SIGNED=$(andamio tx sign --tx "$UNSIGNED_TX" --skey ./payment.skey --output json)
TX_HASH=$(echo "$SIGNED" | jq -r '.tx_hash')
SIGNED_TX=$(echo "$SIGNED" | jq -r '.signed_tx')

# 3. Submit
andamio tx submit --tx "$SIGNED_TX" --output json

# 4. Register
andamio tx register --tx-hash "$TX_HASH" --tx-type access_token_mint

# 5. Check status
andamio tx status "$TX_HASH"

A convenience script is included in the CLI repository at scripts/tx-flow.sh:

./scripts/tx-flow.sh \
  /v2/tx/global/user/access-token/mint \
  '{"alias":"dev1","initiator_data":"addr_test1..."}' \
  ./payment.skey \
  access_token_mint

Transaction Endpoints

The API provides 17 transaction-building endpoints organized by role:

Diagnostic Tools

Verify Task Hashes

Compute task hashes locally and compare against API-returned hashes. Useful for diagnosing hash mismatches with on-chain tasks:

andamio project task verify-hash <project-id>
andamio project task verify-hash <project-id> --output json

This fetches all tasks, computes the Blake2b-256 hash from the Plutus Data CBOR encoding (content, expiration, lovelace, native assets), and reports any mismatches between the API hash and the locally computed hash.

Monitoring Transactions

# Check a specific transaction
andamio tx status <tx-hash>

Transaction states: pending → confirmed → updated (or failed / expired).

Browse available transaction endpoints:

andamio spec paths --filter tx

Security Notes

• Your .skey private key never leaves your machine — signing is purely local
• The CLI warns if your .skey file has overly permissive permissions (should be 0600)
• Submit URLs must use HTTPS (except localhost for development)
• The CLI checks required_signers in the transaction and warns if your key doesn't match