Metadata-Version: 2.4
Name: chain-signer
Version: 0.1.8
Summary: Non-custodial burner-wallet toolkit for AI agents. Your agent holds its own key and signs + posts directly — make a fresh wallet, read balance, send, and swap in a few lines. No MetaMask, no GUI, no account.
Project-URL: Homepage, https://github.com/Kevthetech143/chain-signer
Project-URL: Documentation, https://github.com/Kevthetech143/chain-signer#readme
Author: chain-signer
License: MIT
Keywords: agent-tools,ai-agents,burner-wallet,crypto,ethereum,evm,non-custodial,wallet,web3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: eth-abi
Requires-Dist: eth-account
Requires-Dist: eth-utils
Requires-Dist: web3>=7
Provides-Extra: all
Requires-Dist: base58; extra == 'all'
Requires-Dist: bit; extra == 'all'
Requires-Dist: solders; extra == 'all'
Provides-Extra: bitcoin
Requires-Dist: bit; extra == 'bitcoin'
Provides-Extra: solana
Requires-Dist: base58; extra == 'solana'
Requires-Dist: solders; extra == 'solana'
Description-Content-Type: text/markdown

# chain-signer

<!-- mcp-name: io.github.Kevthetech143/chain-signer -->

Give your AI agent its own non-custodial wallet in one line. Make a fresh (burner) wallet,
check balance, send, and swap — your agent holds its own key and signs locally. No MetaMask,
no browser, no account, no custody.

## Install
```
pip install chain-signer
export ETHERSCAN_API_KEY=...   # for live balance reads + broadcast (Etherscan v2)
```
Bitcoin/Solana support is optional: `pip install "chain-signer[all]"`.

## Quickstart (5 lines)
```python
from chain_signer import burner, send_ether
from chain_signer.balance import get_balance

w = burner()                          # fresh throwaway wallet; the agent owns w.private_key
print(w.address, get_balance(w))      # live on-chain balance
send_ether(w, "0x...recipient", 0.001)  # auto nonce+gas, signed locally, broadcast
```
That's it — your agent just held a wallet and moved funds, no human in the loop.

### Try it offline in 2 seconds (no key, no funds, no network)
```
pip install chain-signer
python examples/quickstart.py   # makes a wallet, signs, proves it recovers + encrypts the key
```

## What you get
- `burner()` — a fresh wallet for a one-off task; discard it when done.
- `restore(key)` — reload a wallet later from its exported private key (same key → same address).
- `send_ether(w, to, amount)` — send in ETH (not wei); nonce, gas, and broadcast handled for you.
- `get_balance(w)` — live balance from the chain (Etherscan v2 indexer, not a flaky public RPC).
- `swap(...)` — token swaps via 0x/Paraswap.
- Optional Solana + Bitcoin wallets via the `[all]` extra.

## Non-custodial guarantee
The private key is generated/loaded locally, used only to sign, and never logged, returned, or
stored by this library. You hold the key; we never touch your funds. That is the whole design.

## Handling the key (read this)
`w.private_key` is the keys to the wallet. Treat it like a password:
- NEVER log it, print it in production, or write it into notes/memory/chat. Anyone who has it controls the funds.
- For a burner holding a few dollars this is low-stakes by design — but the rule still holds.
- To reuse a wallet later, store the key in a secret manager / env var, then `restore(key)`.
- Better: `export_encrypted(w, password)` gives a password-protected keystore dict to store at rest; `load_encrypted(keystore, password)` brings the wallet back. Never store the raw key if you can store the keystore.

## Signing idiom (note for web3.py users)
The wallet does not expose `sign_transaction` / `sign_message` methods. Signing is done by
function helpers you pass the wallet to — e.g. `send_ether(w, to, amount)` signs and broadcasts,
and `sign_message(w, "text")` returns an EIP-191 signature for auth / sign-in flows
(recoverable via eth_account `Account.recover_message`).

## CLI on PATH
`pip install` may warn that the `chain-signer` script dir isn't on your PATH. The library works
regardless; to use the CLI directly, add that dir to PATH or run `python -m chain_signer ...`.

## Tool surface (for any AI / MCP / CLI)
`chain_signer.mcp_server` exposes `list_tools()` and `call_tool(name, arguments)`. CLI:
```
python -m chain_signer list
python -m chain_signer call create_wallet '{"chain":"evm"}'
```

## Responsible use
General-purpose, non-custodial tooling. You are responsible for using it within the laws and
terms of service that apply to you. Not intended or marketed for any restricted or prohibited
trading in your jurisdiction.

## Notes
- Balances/broadcast use the Etherscan v2 indexer (authoritative), never a free public RPC.
- Low-level building blocks (`tx.send`, `call_contract`, explicit nonce/gas) remain available for advanced use.

## Run as an MCP server
chain-signer is also a Model Context Protocol (MCP) server, so MCP-aware agents can use it directly:
```
pip install chain-signer
chain-signer-mcp          # speaks MCP over stdio (JSON-RPC 2.0)
```
Exposes 6 tools: create_wallet, get_balance (balance), send, call_contract, swap, bridge.
