Chainai

chainai — Ethereum Transactions Skill

⚠️ DISCLAIMER — USE AT YOUR OWN RISK

This tool interacts with real blockchain networks and real funds. The author(s) of this tool are not responsible for any loss of funds, damages, or unintended consequences arising from its use. By using this skill, you accept full responsibility for all operations performed.

🔒 MANDATORY SECURITY REQUIREMENTS FOR ALL AGENTS

Agents MUST take every possible action to safeguard CHAINAI_PRIVATE_KEY and all other private keys from exposure. Specifically:

1. NEVER log, print, echo, or display private keys in any user-facing output, logs, chat messages, or debug traces.
2. NEVER store private keys in plain text files, version control, or any persistent storage that is not explicitly encrypted and access-controlled.
3. NEVER transmit private keys over unencrypted channels or include them in URLs, query parameters, or request bodies to third-party services.
4. NEVER include private keys in error messages, stack traces, or diagnostic output.
5. ALWAYS prefer the CHAINAI_PRIVATE_KEY environment variable over the -k flag to minimize key exposure in shell history and process listings.
6. ALWAYS treat private keys as the highest-sensitivity secret. A leaked private key grants full, irrevocable control over all funds in the associated wallet.

🚀 BEFORE YOU BEGIN

1. Verify your private key is set: Run npx chainai@0.0.8 who-am-i to confirm CHAINAI_PRIVATE_KEY is properly configured and resolves to the expected address before proceeding with any other command.
2. No private key? Use npx chainai@0.0.8 gen-wallet to generate a new wallet. Save the returned private key securely (e.g. as an environment variable) — it will not be shown again.
3. Fund your account: You must deposit the necessary funds (native tokens for gas + any tokens you intend to send or swap) to the wallet address before using send, swap, or any transaction-submitting command. Commands will fail if the account has insufficient balance.

Overview

chainai is a non-interactive CLI tool for Ethereum and EVM-compatible blockchain operations. It handles signing, sending, broadcasting transactions, token swaps (1inch Fusion), balance queries, and wallet generation.

Invocation

npx chainai@0.0.8 <command> [options]

• Runtime: Node.js (>=18)
• Non-interactive: All parameters must be passed as arguments or flags. Never prompts for input.

Authentication

Most commands accept a private key via:

• -k, --private-key <key> flag (hex string starting with 0x)
• CHAINAI_PRIVATE_KEY environment variable (fallback when -k is not provided)

Supported Networks

Use -n, --network to specify a network by name, alias, or chain ID. Defaults to mainnet.

Exit Codes

Message Contract

Success (stdout)

CHAINAI_OK: <description>
{ ... }

Errors (stderr)

CHAINAI_ERR: <ERROR_CODE> — <description>

Retry Strategy

For TIMEOUT and EXECUTION_FAILED errors, retry up to 2 times with exponential backoff before escalating.

Commands

gen-wallet

Generate a new random wallet (private key and address).

npx chainai@0.0.8 gen-wallet

Options: None.

Output (stdout):

{
  "address": "0x...",
  "privateKey": "0x..."
}

Usage instructions are printed to stderr.

who-am-i

Return the Ethereum address derived from a private key.

npx chainai@0.0.8 who-am-i -k 0xKEY
# or
CHAINAI_PRIVATE_KEY=0xKEY npx chainai@0.0.8 who-am-i

Options:

Output (stdout):

{
  "address": "0x..."
}

sign-message

Sign a message using EIP-191 personal sign.

npx chainai@0.0.8 sign-message -k 0xKEY -m "Hello World"
npx chainai@0.0.8 sign-message -k 0xKEY -m 0x68656c6c6f --raw

Options:

Output (stdout):

{
  "address": "0x...",
  "message": "<original message>",
  "signature": "0x..."
}

sign

⚠️ CRITICAL SECURITY WARNING: Signs a raw hash (secp256k1) without any prefix. The resulting signature can authorize any on-chain action. Use sign-message instead unless raw hash signing is explicitly required. Before using, verify the hash is legitimate and no safer alternative exists.

npx chainai@0.0.8 sign -k 0xKEY -h 0xHASH

Options:

Output (stdout):

{
  "address": "0x...",
  "hash": "0x...",
  "signature": "0x..."
}

sign-typed-data

Sign EIP-712 typed data.

npx chainai@0.0.8 sign-typed-data -k 0xKEY -d '<json>'

Options:

Data Format:

{
  "domain": {
    "name": "AppName",
    "version": "1",
    "chainId": 1,
    "verifyingContract": "0x..."
  },
  "types": { "TypeName": [{ "name": "fieldName", "type": "fieldType" }] },
  "primaryType": "TypeName",
  "message": { "fieldName": "value" }
}

Output (stdout):

{
  "address": "0x...",
  "signature": "0x..."
}

sign-transaction

Sign a transaction (legacy, EIP-2930, or EIP-1559). Returns a serialized signed transaction ready to broadcast.

npx chainai@0.0.8 sign-transaction -k 0xKEY -t '<json>'

Options:

Transaction Formats:

Legacy:

{
  "to": "0x...",
  "value": "1000000000000000000",
  "gasPrice": "20000000000",
  "gas": "21000",
  "nonce": 0,
  "chainId": 1
}

EIP-1559:

{
  "to": "0x...",
  "value": "1000000000000000000",
  "maxFeePerGas": "30000000000",
  "maxPriorityFeePerGas": "1000000000",
  "gas": "21000",
  "nonce": 0,
  "chainId": 1
}

Omit to for contract deployment. Numeric values can be strings or numbers.

Output (stdout):

{
  "address": "0x...",
  "serializedTransaction": "0x..."
}

get-balance

Get native or ERC-20 token balances.

npx chainai@0.0.8 get-balance -a 0xADDRESS
npx chainai@0.0.8 get-balance -a 0xADDRESS -n bsc
npx chainai@0.0.8 get-balance -a 0xADDRESS -t 0xTOKEN_CONTRACT
npx chainai@0.0.8 get-balance -a 0xADDRESS --all

Options:

Output (stdout) — single token:

{
  "address": "0x...",
  "network": "Ethereum",
  "token": "ETH",
  "balance": "1.5",
  "rawBalance": "1500000000000000000",
  "decimals": 18,
  "contract": null
}

With --all, returns an array of balance objects.

send

Build and sign a transaction to send native tokens or ERC-20 tokens. Automatically fetches nonce, gas, and fee data from the network.

npx chainai@0.0.8 send -k 0xKEY --to 0xRECIPIENT --amount 1.5 -t 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
npx chainai@0.0.8 send -k 0xKEY --to 0xRECIPIENT --amount 100 -t 0xTOKEN_CONTRACT -n bsc

Options:

Output (stdout):

{
  "from": "0x...",
  "to": "0x...",
  "token": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
  "amount": "1.5",
  "network": "Ethereum",
  "serializedTransaction": "0x..."
}

broadcast

Broadcast a serialized signed transaction to the network.

npx chainai@0.0.8 broadcast -s 0xSERIALIZED_TX
npx chainai@0.0.8 broadcast -s 0xSERIALIZED_TX -n bsc

Options:

Output (stdout):

{
  "transactionHash": "0x...",
  "network": "Ethereum",
  "explorerUrl": "https://etherscan.io/tx/0x..."
}

tx-status

Get the status of a transaction by hash.

npx chainai@0.0.8 tx-status -h 0xTX_HASH
npx chainai@0.0.8 tx-status -h 0xTX_HASH -n bsc

Options:

Output (stdout):

{
  "transactionHash": "0x...",
  "status": "success",
  "network": "Ethereum",
  "blockNumber": "12345678",
  "from": "0x...",
  "to": "0x...",
  "gasUsed": "21000",
  "effectiveGasPrice": "30000000000",
  "explorerUrl": "https://etherscan.io/tx/0x..."
}

For pending transactions, status is "pending" and blockNumber, from, to, gasUsed, effectiveGasPrice will be null.

swap

Swap tokens via 1inch Fusion. Gets a quote first, then optionally submits the order. Use -y to skip confirmation and submit immediately.

npx chainai@0.0.8 swap -k 0xKEY --from-token 0xFROM --to-token 0xTO --amount 1.5
npx chainai@0.0.8 swap -k 0xKEY --from-token 0xFROM --to-token 0xTO --amount 1.5 -y
npx chainai@0.0.8 swap -k 0xKEY --from-token 0xFROM --to-token 0xTO --amount 0.5 -n bsc

Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native tokens.

Options:

Output (stdout) — quote:

{
  "from": "0x...",
  "fromToken": "0x...",
  "toToken": "0x...",
  "amount": "1.5",
  "estimatedReturn": "1500",
  "estimatedReturnMin": "1400",
  "estimatedReturnAvg": "1450",
  "network": "Ethereum"
}

Output (stdout) — order submission:

{
  "from": "0x...",
  "fromToken": "0x...",
  "toToken": "0x...",
  "amount": "1.5",
  "estimatedReturn": "1500",
  "estimatedReturnMin": "1400",
  "estimatedReturnAvg": "1450",
  "network": "Ethereum",
  "orderHash": "0x...",
  "approvalTxHash": "0x..."
}

approvalTxHash is non-null only when an ERC-20 token approval was required. For native token swaps or already-approved tokens, it is null.

swap-order-status

Get the status of a 1inch Fusion swap order by its order hash.

npx chainai@0.0.8 swap-order-status -k 0xKEY --order-hash 0xORDER_HASH
npx chainai@0.0.8 swap-order-status -k 0xKEY --order-hash 0xORDER_HASH -n bsc

Options:

Output (stdout):

{
  "orderHash": "0x...",
  "status": "filled",
  "network": "Ethereum",
  "createdAt": 1700000000,
  "duration": 180,
  "fills": [{ "txHash": "0x..." }],
  "cancelTx": null,
  "finalToAmount": "1500000000"
}

Possible status values: "pending", "filled", "expired", "cancelled". For pending/cancelled orders, finalToAmount is null and fills is empty.