tap-cli

Command-line interface for TAP Agent operations. tap-cli enables you to manage agents, create and monitor transactions, perform Travel Rule compliance operations, and interact with the TAP ecosystem from the terminal.

Installation

From crates.io (recommended)

cargo install tap-cli

From source

git clone https://github.com/TransactionAuthorizationProtocol/tap-rs.git
cd tap-rs
cargo install --path tap-cli

Verify installation

tap-cli --help

Prerequisites

Rust 1.71.0 or later

Quick Start

# Create your first agent (generates a new DID automatically)
tap-cli agent create

# Or generate a DID explicitly
tap-cli did generate --save

# Create a transfer
tap-cli transaction transfer \
  --asset eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7 \
  --amount 100.0 \
  --originator did:key:z6Mk... \
  --beneficiary did:key:z6Mk...

Global Flags

Flag	Env Var	Description
`--agent-did <DID>`	`TAP_AGENT_DID`	Use a specific agent DID for operations
`--tap-root <PATH>`	`TAP_ROOT` or `TAP_HOME`	Custom TAP data directory (default: `~/.tap`)
`--format <FORMAT>`		Output format: `json` (default) or `text`
`--debug` / `-d`		Enable debug logging to stderr

If no agent is specified and no stored keys exist, a new agent with a generated DID is created automatically.

Commands

`agent` — Manage Agents

# Create a new agent
tap-cli agent create
tap-cli agent create --label "my-vasp"

# List all registered agents
tap-cli agent list

`did` — DID Operations

# Generate a new DID (did:key by default)
tap-cli did generate
tap-cli did generate --method key --key-type ed25519 --save --label "primary"
tap-cli did generate --method web --domain example.com --save

# Resolve a DID to its DID Document
tap-cli did lookup did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

# Manage stored keys
tap-cli did keys                        # list all keys
tap-cli did keys list
tap-cli did keys view did:key:z6Mk...
tap-cli did keys set-default did:key:z6Mk...
tap-cli did keys delete did:key:z6Mk...
tap-cli did keys relabel did:key:z6Mk... "new-label"

`transaction` — Create and List Transactions

`transaction transfer` — TAIP-3 Transfer (VASP-to-VASP)

tap-cli transaction transfer \
  --asset eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7 \
  --amount 100.0 \
  --originator did:key:z6MkOriginator... \
  --beneficiary did:key:z6MkBeneficiary... \
  --memo "Invoice #1234"

# With agents
tap-cli transaction transfer \
  --asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 500.0 \
  --originator did:key:z6MkOriginator... \
  --beneficiary did:key:z6MkBeneficiary... \
  --agents '[{"@id":"did:key:z6MkAgent...","role":"SourceAgent","for":"did:key:z6MkOriginator..."}]'

Flag	Required	Description
`--asset`	Yes	CAIP-19 asset identifier
`--amount`	Yes	Transfer amount
`--originator`	Yes	Originator DID
`--beneficiary`	Yes	Beneficiary DID
`--agents`	No	Agents as JSON array
`--memo`	No	Optional memo
`--expiry`	No	ISO 8601 expiry timestamp
`--transaction-value`	No	Fiat equivalent as `amount:currency` (e.g., `1000.00:USD`)

`transaction payment` — TAIP-14 Payment Request

# Payment with asset
tap-cli transaction payment \
  --amount 99.99 \
  --merchant did:key:z6MkMerchant... \
  --asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48

# Payment with fiat currency
tap-cli transaction payment \
  --amount 99.99 \
  --merchant did:key:z6MkMerchant... \
  --currency USD \
  --memo "Order #5678"

# With expiry and invoice
tap-cli transaction payment \
  --amount 99.99 \
  --merchant did:key:z6MkMerchant... \
  --asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --expiry "2026-12-31T23:59:59Z" \
  --invoice-url "https://merchant.example.com/invoices/5678" \
  --fallback-addresses eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Flag	Required	Description
`--amount`	Yes	Payment amount
`--merchant`	Yes	Merchant DID
`--asset`	No*	CAIP-19 asset identifier
`--currency`	No*	ISO 4217 currency code (e.g., USD)
`--agents`	No	Agents as JSON array
`--memo`	No	Optional memo
`--expiry`	No	ISO 8601 expiry timestamp
`--invoice-url`	No	Invoice URL (TAIP-16)
`--fallback-addresses`	No	Comma-separated fallback settlement addresses (CAIP-10)

* One of --asset or --currency must be specified.

`transaction connect` — TAIP-15 Connection Request

tap-cli transaction connect \
  --recipient did:key:z6MkRecipient... \
  --for did:key:z6MkParty... \
  --role SourceAgent

# With transaction limits and constraints
tap-cli transaction connect \
  --recipient did:key:z6MkRecipient... \
  --for did:key:z6MkParty... \
  --constraints '{"max_amount":"10000","daily_limit":"50000","allowed_assets":["eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"]}' \
  --expiry "2027-01-01T00:00:00Z" \
  --agreement "https://example.com/terms"

Flag	Required	Description
`--recipient`	Yes	Recipient agent DID
`--for`	Yes	Party DID this connection is for
`--role`	No	Agent role (e.g., SourceAgent)
`--constraints`	No	Constraints JSON (limits, allowed_beneficiaries, allowed_settlement_addresses, allowed_assets)
`--expiry`	No	ISO 8601 expiry timestamp
`--agreement`	No	URL to terms of service or agreement

`transaction escrow` — TAIP-17 Escrow Request

tap-cli transaction escrow \
  --amount 1000.0 \
  --originator did:key:z6MkOriginator... \
  --beneficiary did:key:z6MkBeneficiary... \
  --expiry "2026-12-31T23:59:59Z" \
  --asset eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7 \
  --agents '[{"@id":"did:key:z6MkEscrow...","role":"EscrowAgent","for":"did:key:z6MkOriginator..."}]' \
  --agreement "https://example.com/escrow-terms"

`transaction capture` — Release Escrowed Funds

tap-cli transaction capture --escrow-id <ESCROW_TRANSACTION_ID>

# Partial capture
tap-cli transaction capture \
  --escrow-id <ESCROW_TRANSACTION_ID> \
  --amount 500.0 \
  --settlement-address eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

`transaction exchange` — TAIP-18 Exchange Request

tap-cli transaction exchange \
  --from-assets eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --to-assets eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 \
  --from-amount 1000.00 \
  --requester did:key:z6MkRequester...

# With a specific provider
tap-cli transaction exchange \
  --from-assets eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --to-assets eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 \
  --to-amount 999.50 \
  --requester did:key:z6MkRequester... \
  --provider did:key:z6MkProvider...

`transaction quote` — TAIP-18 Quote Response

tap-cli transaction quote \
  --exchange-id <EXCHANGE_TX_ID> \
  --from-asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --to-asset eip155:137/erc20:0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 \
  --from-amount 1000.00 \
  --to-amount 999.50 \
  --provider did:key:z6MkProvider... \
  --expires "2026-06-30T12:00:00Z"

`transaction list` — Query Transactions

# List all transactions for the current agent
tap-cli transaction list

# Filter by type
tap-cli transaction list --type Transfer

# Filter by thread ID
tap-cli transaction list --thread-id <THREAD_ID>

# Pagination
tap-cli transaction list --limit 20 --offset 40

`action` — Transaction Lifecycle Actions

`action authorize` — TAIP-4 Authorization

tap-cli action authorize --transaction-id <TX_ID>

# With settlement address
tap-cli action authorize \
  --transaction-id <TX_ID> \
  --settlement-address eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
  --expiry "2026-06-30T12:00:00Z"

`action reject` — TAIP-4 Rejection

tap-cli action reject \
  --transaction-id <TX_ID> \
  --reason "AML policy violation"

`action cancel` — TAIP-5 Cancellation

tap-cli action cancel \
  --transaction-id <TX_ID> \
  --by did:key:z6MkRequester... \
  --reason "Customer request"

`action settle` — TAIP-6 Settlement

tap-cli action settle \
  --transaction-id <TX_ID> \
  --settlement-id eip155:1:0xabcdef1234567890...

# Partial settlement
tap-cli action settle \
  --transaction-id <TX_ID> \
  --settlement-id eip155:1:0xabcdef1234567890... \
  --amount 75.0

`action revert` — TAIP-12 Revert

tap-cli action revert \
  --transaction-id <TX_ID> \
  --settlement-address eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb \
  --reason "Fraudulent transaction"

`agent-mgmt` — Agent & Policy Management within Transactions

Manage agents and policies on existing transactions (TAIP-5, TAIP-7).

# Add agents to a transaction
tap-cli agent-mgmt add-agents \
  --transaction-id <TX_ID> \
  --agents '[{"@id":"did:key:z6MkNew...","role":"ComplianceOfficer","for":"did:key:z6MkParty..."}]'

# Remove an agent from a transaction
tap-cli agent-mgmt remove-agent \
  --transaction-id <TX_ID> \
  --agent-to-remove did:key:z6MkOldAgent...

# Replace an agent in a transaction
tap-cli agent-mgmt replace-agent \
  --transaction-id <TX_ID> \
  --original did:key:z6MkOldAgent... \
  --new-agent '{"@id":"did:key:z6MkNewAgent...","role":"SourceAgent","for":"did:key:z6MkParty..."}'

# Update transaction policies
tap-cli agent-mgmt update-policies \
  --transaction-id <TX_ID> \
  --policies '[{"@type":"RequireAuthorization"}]'

`comm` — Communication

# Send a trust ping to verify agent connectivity
tap-cli comm ping --recipient did:key:z6MkRecipient...

# Send a basic text message
tap-cli comm message \
  --recipient did:key:z6MkRecipient... \
  --content "Hello, this is a test message"

`customer` — Customer Management

# List customers
tap-cli customer list
tap-cli customer list --limit 20 --offset 0

# Create a customer with a Schema.org profile
tap-cli customer create \
  --customer-id did:key:z6MkCustomer... \
  --profile '{"@type":"Person","name":"Alice Smith","email":"alice@example.com"}'

# View customer details
tap-cli customer details --customer-id did:key:z6MkCustomer...

# Update a customer profile
tap-cli customer update \
  --customer-id did:key:z6MkCustomer... \
  --profile '{"@type":"Person","name":"Alice Smith","email":"new@example.com"}'

# Generate IVMS101 data for Travel Rule compliance
tap-cli customer ivms101 --customer-id did:key:z6MkCustomer...

`decision` — Decision Log Management

Decisions are created when the TAP node reaches a decision point in the transaction lifecycle (e.g., authorization needed, settlement required). In poll mode, they accumulate in the database for external systems to act on.

# List all pending decisions
tap-cli decision list --status pending

# List all decisions (any status)
tap-cli decision list

# Paginate through decisions
tap-cli decision list --since-id 100 --limit 20

# Resolve a decision by authorizing the transaction
tap-cli decision resolve --decision-id 42 --action authorize

# Resolve with additional detail
tap-cli decision resolve --decision-id 42 --action authorize \
  --detail '{"settlement_address":"eip155:1:0xABC"}'

# Reject a decision
tap-cli decision resolve --decision-id 42 --action reject

# Defer a decision (mark as seen, will act later)
tap-cli decision resolve --decision-id 42 --action defer

Decision types:

authorization_required — New transaction needs approval
policy_satisfaction_required — Policies must be fulfilled
settlement_required — All agents authorized, ready to settle

Decision statuses: pending, delivered, resolved, expired

Note: The action commands (authorize, reject, settle, cancel, revert) automatically resolve matching decisions when they succeed. You can use either decision resolve for fine-grained control or action commands for the common case.

`delivery` — Message Delivery Tracking

# List deliveries for a recipient
tap-cli delivery list --recipient did:key:z6MkRecipient...

# List deliveries for a message
tap-cli delivery list --message <MESSAGE_ID>

# List deliveries for a transaction thread
tap-cli delivery list --thread <THREAD_ID>

# With pagination
tap-cli delivery list --recipient did:key:z6MkRecipient... --limit 20 --offset 0

`received` — Received Message Inspection

# List all received messages
tap-cli received list

# List pending (unprocessed) messages
tap-cli received pending

# View a specific message by its numeric ID
tap-cli received view 42

# With explicit agent DID
tap-cli received list --agent-did did:key:z6Mk...

Output Formats

All commands output JSON by default. Use --format text for a more readable format in interactive sessions.

# JSON output (default, good for scripting)
tap-cli --format json transaction list

# Text output (good for human reading)
tap-cli --format text agent list

JSON output can be piped through jq for filtering:

tap-cli transaction list | jq '.transactions[] | select(.type | contains("Transfer"))'

Environment Variables

Variable	Description
`TAP_ROOT`	TAP data directory (also `TAP_HOME`)
`TAP_AGENT_DID`	Default agent DID to use

Storage

tap-cli stores data under ~/.tap/ by default:

~/.tap/
├── keys.json           # Stored DID keys
└── agents/
    └── <did-hash>/
        └── storage.db  # Per-agent SQLite database

Use --tap-root or TAP_ROOT to point to a different directory.

Complete Workflow Example

# 1. Generate and save a DID
tap-cli did generate --method key --save --label "vasp-agent"

# 2. Verify it's stored
tap-cli did keys list

# 3. Initiate a transfer
RESULT=$(tap-cli transaction transfer \
  --asset eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  --amount 250.00 \
  --originator did:key:z6MkOriginator... \
  --beneficiary did:key:z6MkBeneficiary...)

TX_ID=$(echo "$RESULT" | jq -r '.transaction_id')

# 4. Authorize the transaction
tap-cli action authorize \
  --transaction-id "$TX_ID" \
  --settlement-address eip155:1:0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

# 5. Settle once on-chain confirmation is received
tap-cli action settle \
  --transaction-id "$TX_ID" \
  --settlement-id eip155:1:0xabcdef1234...

# 6. Review the transaction log
tap-cli transaction list | jq '.transactions[] | {id, type, direction, created_at}'

Related Packages

tap-agent — Core agent and key management
tap-node — TAP node orchestration
tap-msg — TAP message types
tap-http — HTTP server for DIDComm transport
tap-mcp — AI assistant integration via MCP

License

MIT — see LICENSE-MIT.

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

tap-cli

Installation

From crates.io (recommended)

From source

Verify installation

Prerequisites

Quick Start

Global Flags

Commands

agent — Manage Agents

did — DID Operations

transaction — Create and List Transactions

transaction transfer — TAIP-3 Transfer (VASP-to-VASP)

transaction payment — TAIP-14 Payment Request

transaction connect — TAIP-15 Connection Request

transaction escrow — TAIP-17 Escrow Request

transaction capture — Release Escrowed Funds

transaction exchange — TAIP-18 Exchange Request

transaction quote — TAIP-18 Quote Response

transaction list — Query Transactions

action — Transaction Lifecycle Actions

action authorize — TAIP-4 Authorization

action reject — TAIP-4 Rejection

action cancel — TAIP-5 Cancellation

action settle — TAIP-6 Settlement

action revert — TAIP-12 Revert

agent-mgmt — Agent & Policy Management within Transactions

comm — Communication

customer — Customer Management

decision — Decision Log Management

delivery — Message Delivery Tracking

received — Received Message Inspection