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

For hash verification and diagnostics (compute-hash, verify-hash for both courses and tasks), see Hash Verification.

Inspection Commands

Transaction Status

andamio tx status <tx-hash>

States: pending → confirmed → updated (or failed / expired). See Error Handling for recovery actions per state.

Pending Transactions

List your in-flight transactions:

andamio tx pending
andamio tx pending --output json

Transaction Types

List all valid tx_type values accepted by tx register and tx run:

andamio tx types

Browse Endpoints

andamio spec paths --filter tx
andamio spec fetch  # Download full OpenAPI spec to openapi.json

Exit Codes

All CLI commands use consistent exit codes for scripting:

andamio tx status abc123...
if [ $? -eq 2 ]; then
  echo "Transaction not found"
fi

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