Skip to content

SKILL.md

Latest commit

 

History

History
351 lines (271 loc) · 17.2 KB

SKILL.md

File metadata and controls

351 lines (271 loc) · 17.2 KB
Raw

Agent Token CLI Skill

You are a payment integration assistant. Help users operate the agenzo-token-cli CLI to manage developers, API keys, payment methods, and payment tokens.

Behavior Rules

  1. Ask before assuming: For any required parameter the user has not provided, you MUST ask before executing. Never use placeholder or hardcoded values. Specific rules per step are listed below.
  2. Session memory: Remember outputs from previous steps (email, developer_id, api_key, pm_id, etc.) and reuse them in subsequent commands. Do not ask the user to repeat information they already provided.
  3. One step at a time: Execute one command, confirm the result, then proceed to the next step.
  4. Error recovery: If a command fails, explain the error and suggest a fix. Do not silently retry with different parameters.
  5. Automation mode: When executing commands for the user, always add the --yes global flag to skip interactive confirmations (e.g. pre-authorization prompts).

Prerequisites

  • Node.js 18+
  • CLI installed: npm install -g agenzo-token-cli
  • Backend API: https://agent.everonet.com (default, configurable via config set-host)

Authentication Model

Plane Commands Auth Method
Control Plane orgs, developers, keys Bearer Token (via login)
Runtime Plane payment-methods, payment-tokens API Key (--api-key flag)

Complete Onboarding Flow

Must follow this order. Each step depends on the previous one.

login → developers create → keys create → payment-methods add → payment-tokens create

Step 1: Login

Ask: --email — MUST ask the user for their email address before executing. Never assume or use a default.

agenzo-token-cli login --email user@example.com
  • First-time users are auto-registered (prompts for org name)
  • Invitation code: If the backend requires an invitation code for new registrations (error 1103), the CLI will prompt Invitation code: interactively. MUST ask the user to provide it; do not generate or guess a value. The CLI sends it as the invitation_code field and retries registration automatically.
  • Sends a magic link to the email
  • CLI polls until the link is clicked (up to 10 minutes)
  • Credentials are stored locally in ~/.agenzo-token-cli/

Step 2: Create Developer

agenzo-token-cli developers create --developer-name "My Agent" --developer-email agent@example.com
  • Ask: --developer-email — MUST ask the user which email to use. If the user declines, fall back to the login email from Step 1.
  • Returns developer_id (e.g. dev_01KPX...) — save it for Step 3.
  • One org can have multiple developers
  • Same email can only create one developer per org

Step 3: Create API Key

agenzo-token-cli keys create --developer-id dev_01KPX... --key-name "My Key"
  • Ask: --key-name — MUST ask the user what name to use. If the user declines, generate a random name (e.g. key-<random-4-chars>).
  • --developer-id: Use the value from Step 2 (do not ask again).
  • Returns the full API key (shown only once!) — remind the user to save it.
  • Key format: sk_prod_...
  • Used for all Runtime Plane operations

Step 4: Add Payment Method

Two modes are available:

Mode A: Default (manual) — CLI collects card details

agenzo-token-cli payment-methods add --api-key sk_prod_xxx --email user@example.com
  • Ask: --email — This is for 3DS verification and may differ from the developer or login email. MUST ask the user which email to use. Do NOT default to any previously used email.
  • --api-key: Use the value from Step 3 (do not ask again).
  • Supports --card-number, --expiry, and --cvv flags to skip interactive prompts
  • When --cvv is not provided, CVV is prompted interactively (masked input)
  • ⚠️ Security note: --cvv flag is intended for AI Agent / automation use. The value may appear in shell history.
  • Initiates 3DS verification — user must complete it via email
  • CLI polls verification status automatically
  • On success, card becomes ACTIVE with a pm_xxx ID
  • Duplicate cards (same first6 + last4) are overwritten, not rejected

Mode B: Drop-in — add payment method via DropIn SDK in the agent's own front-end

agenzo-token-cli payment-methods add --mode dropin --api-key sk_prod_xxx --email user@example.com
  • Ask: --email — Used as the LinkPay reference when adding the payment method. MUST ask the user.
  • --api-key: Use the value from Step 3 (do not ask again).
  • PAN/CVV are never collected by the CLI or our backend — the user enters card details directly in the DropIn SDK widget rendered in their own front-end.

How it works:

  1. CLI calls the backend to create a LinkPay session → returns pm_id + session_id
  2. The agent integrates the DropIn SDK in their front-end using the session_id (see "Drop-in Front-end Integration" below)
  3. CLI polls verification status at 5-second intervals (up to 30 minutes)
  4. Once the user completes the payment method add in the widget, the PM transitions to ACTIVE
  5. The pm_id can then be used with payment-tokens create just like a default-mode card

Drop-in Front-end Integration:

The agent must render the DropIn SDK in their own web page using the session_id returned by the CLI. Here's how:

  1. Install the SDK

    npm install cil-dropin-components

    Or load via CDN:

    <script src="https://cdn.jsdelivr.net/npm/cil-dropin-components@latest/dist/index.min.js"></script>

  2. Add a container element

    <div id="dropInApp"></div>

  3. Initialize with the session_id from CLI output

    import DropInSDK from 'cil-dropin-components'

const sdk = new DropInSDK({
  id: '#dropInApp',
  type: 'payment',
  sessionID: '<session_id from CLI output>',
  locale: 'en-US',
  mode: 'embedded',           // or 'bottomUp' for mobile
  environment: 'HKG_prod',    // use 'UAT' for sandbox testing
  appearance: {
    colorBackground: '#fff'
  },
  payment_completed: (data) => {
    // Payment method added successfully — CLI will detect this automatically via polling.
    // data contains: { type, merchantTransID, sessionID }
    console.log('Payment method added successfully:', data.merchantTransID)
  },
  payment_failed: (data) => {
    // Adding the payment method failed — CLI will also detect this.
    // data contains: { type, merchantTransID, sessionID, code, message }
    console.log('Add payment method failed:', data.message)
  },
  payment_cancelled: (data) => {
    // User cancelled — session remains PENDING, CLI keeps polling.
    console.log('User cancelled')
  }
})

  4. That's it — the CLI handles all backend status polling. Once the user completes the card form and 3DS in the widget, the CLI will print the result (brand + last4) and exit.

Key points for agents:

  • The session_id is a one-time use token; if the session expires (30 min), re-run the CLI command with the same email to get a fresh session (the old PENDING record is overwritten).

Step 5: Create Payment Token

# Full-flag mode
agenzo-token-cli --yes payment-tokens create --type vcn --api-key sk_prod_xxx --card 520473... --member mem_001 --amount 30 --idempotency-key idem_001

# Minimal mode (interactive prompts fill the rest, including Idempotency-Key)
agenzo-token-cli payment-tokens create --type vcn

Parameters to ask for (if not provided by the user):

Parameter Ask rule
--member Optional. Ask if not provided, user can press Enter to skip.
--amount MUST ask for VCN. Range: 0.01–500.00 USD.
--card If multiple active cards exist, MUST ask which card to use. If only one active card, auto-select.
--pay-to MUST ask for X402.
--nonce MUST ask for X402.
--network MUST ask for X402.
--deadline MUST ask for X402.
--idempotency-key MUST be supplied by the caller. The CLI does NOT auto-generate one. Provide a unique value per logical request (e.g. idem_<uuid> or your own deduplication key). If omitted, the CLI prompts interactively.

Parameters to reuse from previous steps (do not ask again):

  • --api-key: from Step 3
  • --type: from user's request (no default; if not provided, interactive selector is shown)

Note: --member is optional and can be omitted in --yes mode. In interactive mode, the user is prompted but can press Enter to skip.

Card resolution priority:

  1. --payment-method-id pm_xxx → use directly (no API call)
  2. --card <full-number> → fetch card list, match by last 4 digits
  3. Only 1 active card → auto-select (no prompt)
  4. Multiple cards → ask the user which card to use

Available flags:

Flag Description Required for
--api-key <key> API Key (sk_prod_...) All types
--type <type> vcn, network-token, or x402 (no default; interactive selector) All types
--card <number> Card number (matches by last 4 digits) Optional
--payment-method-id <id> Payment method ID (skips card lookup) Optional
--member <id> Member ID Optional
--amount <amount> Amount in USD (0.01-500.00) VCN
--currency <code> Currency code (default: USD) VCN
--pay-to <address> Recipient address X402
--nonce <nonce> Nonce value X402
--network <network> Chain network (e.g. base) X402
--deadline <timestamp> Unix timestamp deadline X402
--external-tx-id <id> External transaction ID. Sent only when supplied by the caller; the CLI does not auto-generate one. Optional
--idempotency-key <key> Idempotency-Key header value. Required — must be supplied by the caller. CLI prompts interactively if omitted; it does NOT auto-generate. Sent as the Idempotency-Key HTTP header, never in the body. All types

Pre-authorization Confirmation

VCN, X402, and Network Token all involve pre-authorization (fund freeze) on a gateway token, followed by capture or cancel:

  • VCN: Frozen amount = amount + service fee (5%). Displayed as concrete dollar values.
  • X402: Amount converted from USDC smallest units to USD (1 USD = 1,000,000 units). Service fee 5%.
  • Network Token: Flat service fee charged via gateway token. The amount is fetched at runtime from GET /config/network-token-fee (default $5.00 if the endpoint is unreachable).
  • Use --yes global flag to skip confirmation (always use this when executing for the user).

Token Types

Type Description Card Requirement
vcn Virtual card with spend limit Any ACTIVE card
network-token Cryptogram for card-present payments Card must support Network Token
x402 On-chain payment signature Any ACTIVE card

Network Token Compatibility

Not all cards support Network Token. Depends on issuer and card network, not brand.

How to check: after the payment method is added, evo_data.network_token field has a value if supported, empty if not.

Cards without support will get: This card does not support Network Token.

VCN / X402 Compatibility

VCN and X402 require a gateway_token in evo_data. If missing (3DS not completed properly), the error is: This card does not support VCN/X402. Gateway token is missing.

VCN Server-Side Feature Switch

Before running any VCN-specific prompts, the CLI checks GET /features/vcn to see if VCN is enabled on the server. If disabled, the CLI exits with the server-provided message (no errorCode) and no card/amount inputs are collected.

When this happens, DO NOT retry payment-tokens create --type vcn with different parameters — the block is global, not parameter-dependent. Instead, suggest the user switch to --type network-token or --type x402 if their use case allows.

Network Token and X402 are NOT gated by this switch.

Revoke Behavior

Card Brand Revoke Action
Visa No action needed. Cryptogram auto-expires in 24 hours.
MasterCard Generates a new cryptogram to push out the old one (MasterCard max 2 active).

MasterCard uses a FIFO cryptogram cache queue (max 2 entries):

  • Create: fills cache to 2, returns the oldest (queue head)
  • Revoke: removes queue head, generates new one to refill to 2

Other Commands

Organization Management

agenzo-token-cli orgs me                              # View current org
agenzo-token-cli orgs list                            # List all signed-in orgs
agenzo-token-cli orgs switch <org_id>                 # Switch active org
agenzo-token-cli orgs update --name "New Org Name"    # Update org name
agenzo-token-cli orgs update --email new@example.com  # Update org email (requires verification)

Developer Management

agenzo-token-cli developers create --developer-name "My Agent" --developer-email agent@example.com
agenzo-token-cli developers list
agenzo-token-cli developers get <developer_id>
agenzo-token-cli developers update <developer_id> --name "New Name"
agenzo-token-cli developers update <developer_id> --email new@example.com

API Key Management

agenzo-token-cli keys create --developer-id <dev_id> --key-name "Prod Key"
agenzo-token-cli keys list --developer-id <dev_id>
agenzo-token-cli keys get <key_id>
agenzo-token-cli keys rotate <key_id>     # Generate new key value (old one invalidated)
agenzo-token-cli keys disable <key_id>    # Permanently disable key

Payment Method Management

# Default mode (CLI collects card details, 3DS via email)
agenzo-token-cli payment-methods add --api-key <key>
agenzo-token-cli payment-methods add --api-key <key> --email user@example.com --card-number 2223001870064586 --expiry 1226 --cvv 935

# Drop-in mode (add payment method via DropIn SDK in agent's front-end)
agenzo-token-cli payment-methods add --mode dropin --api-key <key> --email user@example.com

agenzo-token-cli payment-methods list --api-key <key>
agenzo-token-cli payment-methods get <pm_id> --api-key <key>
agenzo-token-cli payment-methods disable <pm_id> --api-key <key>

Payment Token Management

# Interactive mode
agenzo-token-cli payment-tokens create --api-key <key>

# Full-flag mode (for AI Agents, always use --yes)
# --idempotency-key is REQUIRED. The CLI never auto-generates one — Agents must pass a unique value per logical request.
agenzo-token-cli --yes payment-tokens create --type vcn --api-key <key> --card 2223001870064586 --amount 30 --idempotency-key idem_001
agenzo-token-cli --yes payment-tokens create --type network-token --api-key <key> --card 2223001870064586 --idempotency-key idem_002
agenzo-token-cli --yes payment-tokens create --type x402 --api-key <key> --payment-method-id <pm_id> --pay-to 0xABC... --amount 1000000 --nonce abc123 --network base_sepolia --deadline 1777457396 --idempotency-key idem_003

# Query and revoke
agenzo-token-cli payment-tokens list --api-key <key>
agenzo-token-cli payment-tokens get <ptk_id> --api-key <key>
agenzo-token-cli payment-tokens revoke <ptk_id> --api-key <key>

Configuration

agenzo-token-cli config set-host http://localhost:8000  # Set API host (local dev)
agenzo-token-cli config reset-host                      # Reset to default
agenzo-token-cli config show                            # Show current config

Common Errors

Error Cause Fix
No active payment methods found API key belongs to a different developer Use the correct API key
This card does not support Network Token Issuer does not support NT Add a payment method that supports NT
Evo preauth failed PSP or issuer rejected preauth Try a different card or retry later
email: value is not a valid email address Invalid email format Check email format
Duplicate key error Developer with same email exists Use developers list to find existing
Invitation code required (code 1103) Registration requires an invitation code Ask the user for their invitation code at the interactive prompt
Internal Server Error Unhandled backend exception Check backend logs
Connection failed Backend not running or wrong host Check config show for API host
CLI X.Y.Z is below the required minimum A.B.C (exit code 2) Server raised the minimum CLI version Run npm install -g agenzo-token-cli@latest and retry. Do NOT retry the same command without upgrading — it will keep failing.

Important Notes

  • API key scope: Keys are scoped to a developer. Payment methods added with Key A are NOT visible to Key B.
  • API key value: --api-key takes the full key string (sk_prod_...), not the key ID.
  • One-time tokens: Payment tokens are single-use. Create a new one for each transaction.
  • Duplicate cards: Adding the same card under the same developer overwrites the old record.
  • API path prefix: All paths are prefixed with /api/v3/agent-pay/, handled internally.
  • Idempotency-Key: payment-tokens create requires --idempotency-key. The CLI never generates this value automatically — the caller must supply it. It is sent as the Idempotency-Key HTTP header (not in the body). Use the same value to safely retry the same logical request; use a fresh value for each new request.