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. 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.

� ADDRESS FORMATTING RULES

1. 1. Always use ERC-55 checksum addresses when passing addresses to any command (wallet addresses, token contract addresses, recipient addresses, etc.).
2. If you do not know the correct checksum, use all lowercase addresses (e.g. 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 instead of guessing the mixed-case checksum).
3. Never guess a token contract address. If you are unsure of the correct token contract address, always ask the user to provide it. Do not fabricate or assume token addresses.

�🚀 BEFORE YOU BEGIN

1. 1. Verify your private key is set: Run npx chainai@0.0.10 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.10 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

INLINECODE9 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

CODEBLOCK0

• - 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)
• INLINECODE12 environment variable (fallback when -k is not provided)

Supported Networks

Name	Chain ID	Aliases	Native Token
Ethereum	1	INLINECODE14, ethereum, INLINECODE16	ETH
BNB Smart Chain

56 | bsc, binance, bnb | BNB |

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

Exit Codes

Code	Meaning
INLINECODE22	Operation completed successfully.
INLINECODE23

Operation failed. Inspect stderr for a structured error message. |

Message Contract

Success (stdout)

CODEBLOCK1

Errors (stderr)

CODEBLOCK2

Error Code	Description	Agent Action
INLINECODE25	Malformed or missing required fields.	Re-validate input parameters and retry.
INLINECODE26

Operation could not be completed. Description contains failure details. | Inspect description and adjust approach. |
| TIMEOUT | Operation exceeded the allowed time limit. | Retry with a longer timeout or simplify the request. |
| UNKNOWN | Unexpected error. | Report to orchestrator for manual inspection. |

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).

CODEBLOCK3

Options: None.

Output (stdout):

CODEBLOCK4

Usage instructions are printed to stderr.

---

who-am-i

Return the Ethereum address derived from a private key.

CODEBLOCK5

Options:

Flag	Required	Description
INLINECODE34	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.

Output (stdout):

CODEBLOCK6

---

sign-message

Sign a message using EIP-191 personal sign.

CODEBLOCK7

Options:

Flag	Required	Description
INLINECODE37	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE39

Yes | The message to sign. |
| -r, --raw | No | Treat message as raw hex data (0x-prefixed). |

Output (stdout):

CODEBLOCK8

---

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.

CODEBLOCK9

Options:

Flag	Required	Description
INLINECODE44	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE46

Yes | The hash to sign (0x-prefixed hex string). |

Output (stdout):

CODEBLOCK10

---

sign-typed-data

Sign EIP-712 typed data.

CODEBLOCK11

Options:

Flag	Required	Description
INLINECODE49	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE51

Yes | EIP-712 typed data as JSON with domain, types, primaryType, message. |

Data Format:

CODEBLOCK12

Output (stdout):

CODEBLOCK13

---

sign-transaction

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

CODEBLOCK14

Options:

Flag	Required	Description
INLINECODE57	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE59

Yes | Transaction object as JSON string. |

Transaction Formats:

Legacy:

CODEBLOCK15

EIP-1559:

CODEBLOCK16

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

Output (stdout):

CODEBLOCK17

---

get-balance

Get native or ERC-20 token balances.

CODEBLOCK18

Options:

Flag	Required	Description
INLINECODE62	No	Wallet address. Falls back to address derived from CHAINAI_PRIVATE_KEY.
INLINECODE64

No | Network (default: mainnet). |
| -t, --token <token> | No | Token contract address. Default: 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee (native). |
| --all | No | Return all token balances (native + ERC-20). -t is ignored when set. |

Output (stdout) — single token:

CODEBLOCK19

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.

CODEBLOCK20

Options:

Flag	Required	Description
INLINECODE72	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE74

Yes | Recipient address. |
| -t, --token <token> | Yes | Token contract address. Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native. |
| --amount <amount> | Yes | Amount in human-readable units (e.g. "1.5"). |
| -n, --network <network> | No | Network (default: mainnet). |
| -b, --broadcast | No | Automatically broadcast after signing. |

Output (stdout):

CODEBLOCK21

---

broadcast

Broadcast a serialized signed transaction to the network.

CODEBLOCK22

Options:

Flag	Required	Description
INLINECODE83	Yes	Serialized signed transaction (0x-prefixed).
INLINECODE85

No | Network (default: mainnet). |

Output (stdout):

CODEBLOCK23

---

tx-status

Get the status of a transaction by hash.

CODEBLOCK24

Options:

Flag	Required	Description
INLINECODE88	Yes	Transaction hash (0x-prefixed, 32 bytes).
INLINECODE90

No | Network (default: mainnet). |

Output (stdout):

CODEBLOCK25

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.

CODEBLOCK26

Use 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee for native tokens.

Options:

Flag	Required	Description
INLINECODE103	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE105

Yes | Source token contract address. |
| --to-token <address> | Yes | Destination token contract address. |
| --amount <amount> | Yes | Amount in human-readable units (e.g. "1.5"). |
| -n, --network <network> | No | Network (default: mainnet). |
| -y, --yes | No | Skip confirmation prompt and submit immediately. |

Output (stdout) — quote:

CODEBLOCK27

Output (stdout) — order submission:

CODEBLOCK28

INLINECODE112 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.

CODEBLOCK29

Options:

Flag	Required	Description
INLINECODE115	No	Private key. Falls back to CHAINAI_PRIVATE_KEY.
INLINECODE117

Yes | Order hash returned from the swap command. |
| -n, --network <network> | No | Network (default: mainnet). |

Output (stdout):

CODEBLOCK30

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