CoinFello CLI Skill

Use the npx @coinfello/agent-cli@latest CLI to interact with CoinFello. The CLI handles smart account creation, SIWE authentication, delegation management, prompt-based transactions, and transaction status checks.

Prerequisites

• - Node.js 20 or later (npx is included with Node.js)

The CLI is available via npx @coinfello/agent-cli@latest. No manual build step is required.

Environment Variables

Variable	Required	Default	Description
INLINECODE2	No	INLINECODE3	Base URL for the CoinFello API
INLINECODE4

No | — | QuickNode RPC base URL (e.g. https://your-endpoint-name) | | RPC_API_KEY | No | — | QuickNode API key | | RPC_URL_OVERRIDE | No | — | Custom RPC URL override for development/testing (overrides all other RPC settings) |

If both RPC_BASE_URL and RPC_API_KEY are set, the CLI routes RPC requests through QuickNode for supported chains (Ethereum, Optimism, BSC, Polygon, Mantle, Base, Arbitrum, Linea, Sepolia, Base Sepolia). If either is missing or the chain is not supported, it falls back to the chain's default public RPC.

Set RPC_URL_OVERRIDE (e.g. http://127.0.0.1:8545) to route all RPC calls through a custom URL, regardless of chain or other RPC settings.

Security Notice

This skill performs the following sensitive operations:

• - Key generation and storage: By default, create_account generates a hardware-backed P256 key in the macOS Secure Enclave (or TPM 2.0 where available). The private key never leaves the hardware and cannot be exported — only public key coordinates and a key tag are saved to ~/.clawdbot/skills/coinfello/config.json. If hardware key support is not available, the CLI warns and falls back to a software private key. You can also explicitly opt into a plaintext software key by passing --use-unsafe-private-key, which stores a raw private key in the config file — this is intended only for development and testing.
• Signer daemon: Running signer-daemon start authenticates once via Touch ID / password and caches the authorization. All subsequent signing operations reuse this cached context, eliminating repeated auth prompts. The daemon communicates over a user-scoped Unix domain socket with restricted permissions (0600). If the daemon is not running, signing operations fall back to direct execution (prompting Touch ID each time).
• Session token storage: Running sign_in stores a SIWE session token in the same config file.
• Delegation signing: Running send_prompt may receive a delegation request from the server, which is saved to a local file. Running approve_delegation_request creates and signs the delegation, then submits it to the CoinFello API.

Users should ensure they trust the CoinFello API endpoint configured via COINFELLO_BASE_URL before running delegation flows.

Quick Start

CODEBLOCK0

Commands

create_account

Creates a MetaMask Hybrid smart account. By default, the signing key is generated in the macOS Secure Enclave (hardware-backed, non-exportable). If Secure Enclave is unavailable, the CLI warns and falls back to a software key. Pass --use-unsafe-private-key to explicitly use a plaintext software key (development/testing only).

CODEBLOCK1

• - Default (Secure Enclave): Generates a P256 key in hardware; saves key_tag, public_key_x, public_key_y, key_id, and smart_account_address to ~/.clawdbot/skills/coinfello/config.json. The private key never leaves the Secure Enclave.
• --use-unsafe-private-key: Generates a random secp256k1 private key and stores it in plaintext in the config file. Use only for development and testing.
• Must be run before INLINECODE29

get_account

Displays the current smart account address from local config.

CODEBLOCK2

• - Prints the stored INLINECODE30
• Exits with an error if no account has been created yet

sign_in

Authenticates with CoinFello using Sign-In with Ethereum (SIWE) and your smart account. Saves the session token to local config.

CODEBLOCK3

• - Signs in using the private key stored in config
• Saves the session token to INLINECODE31
• The session token is loaded automatically for subsequent send_prompt calls
• Must be run after create_account and before send_prompt for authenticated flows

set_delegation

Stores a signed parent delegation (JSON) in local config.

CODEBLOCK4

• - <delegation-json> — A JSON string representing a Delegation object from MetaMask Smart Accounts Kit

new_chat

Clears the saved chat session ID from local config so the next send_prompt starts a fresh conversation.

CODEBLOCK5

• - Removes chat_id from INLINECODE39
• Use this when you want to reset conversation context (for example, after context-window errors)

signer-daemon

Manages the Secure Enclave signing daemon. Starting the daemon authenticates once via Touch ID / password and caches the authorization, so subsequent signing operations (account creation, sign-in, delegation signing) do not prompt again.

CODEBLOCK6

• - If the daemon is not running, all Secure Enclave operations fall back to direct execution (prompting Touch ID each time)
• The daemon is optional — all commands work without it

send_prompt

Sends a natural language prompt to CoinFello. If the server requires a delegation to execute the action, the CLI saves the delegation request to a local file and logs the details to the terminal for review. The delegation is not signed automatically — you must explicitly approve it with approve_delegation_request.

CODEBLOCK7

Note that if you receive
Failed to send prompt: Conversation request failed (400): {"error":"Your input exceeds the context window of this model. Please adjust your input or start a new chat and try again."}
then you should call npx @coinfello/agent-cli@latest new_chat to start a new chat with a new context window.

What happens internally:

1. 1. Fetches available agents from /api/v1/automation/coinfello-agents and sends the prompt to CoinFello's conversation endpoint
2. If the server returns a read-only response (no clientToolCalls and no txn_id) → prints the response text and exits
3. If the server returns a txn_id directly with no tool calls → prints it and exits
4. If the server sends an ask_for_delegation client tool call with a chainId and scope:

- Saves the delegation request (scope, chain ID, call ID, chat ID) to ~/.clawdbot/skills/coinfello/pending_delegation.json - Logs a human-readable summary of the delegation request to the terminal - Exits without signing — run approve_delegation_request to approve

approvedelegationrequest

Approves and signs a pending delegation request saved by send_prompt, then submits it to CoinFello.

CODEBLOCK8

What happens internally:

1. 1. Reads the pending delegation from INLINECODE53
2. Fetches CoinFello's delegate address
3. Rebuilds the smart account using the chain ID from the delegation request
4. Parses the scope and creates a subdelegation (wraps with ERC-6492 signature if the smart account is not yet deployed on-chain)
5. Sends the signed delegation back as a clientToolCallResponse along with the chatId and INLINECODE56
6. Clears the pending delegation file
7. Returns a txn_id for tracking

Common Workflows

Basic: Send a Prompt (Server-Driven Delegation)

CODEBLOCK9

Read-Only Prompt

Some prompts don't require a transaction. The CLI detects this automatically and just prints the response.

CODEBLOCK10

Gas Cost Estimates

Actual on-chain gas costs vary by network. Do not assume mainnet Ethereum gas prices for L2 chains.

Network	Swap / Transfer Gas Cost
Base	$0.0003 – $0.0006

These are approximate ranges under normal network conditions. L2s like Base are significantly cheaper than Ethereum mainnet.

Edge Cases

• - No smart account: Run create_account before send_prompt. The CLI checks for a saved private key and address in config.
• Not signed in: Run sign_in before send_prompt if the server requires authentication.
• Invalid chain name: The CLI throws an error listing valid viem chain names.
• Unsupported chain: The CLI rejects chains where CoinFello infrastructure and MetaMask delegation contracts aren't available. Supported chains: Ethereum, OP Mainnet, BNB Smart Chain, Polygon, Mantle, Base, Arbitrum One, Linea, Sepolia, Base Sepolia. Funding a smart account on any other chain will result in permanently locked funds.
• Read-only response: If the server returns a text response with no transaction, the CLI prints it and exits without creating a delegation.

Bug Reports & Support

If you encounter a bug or unexpected behavior that cannot be resolved by following the troubleshooting steps, email support@coinfello.com with a description of the issue and any relevant error output.

Reference

See references/REFERENCE.md for the full config schema, supported chains, API details, scope types, and troubleshooting.