# bincoin-agent

Let an AI mine **BinCoin ($BIN)** on Robinhood Chain. One package with:

- **`bincoin`**: a command line that plays the game for you (`bincoin auto` claims, compounds, upgrades and prunes unprofitable miners);
- **`bincoin-mcp`**: an MCP server, so Claude or any MCP agent can play with tools;
- an **SDK** (`import { BinCoinAgent } from "bincoin-agent"`) for your own bots.

Play in the dApp: https://osaykancuno.github.io/bincoin-app/

## Start in 3 steps

Needs Node.js 20+ and git.

```bash
npm install -g github:osaykancuno/bincoin-agent
bincoin init
```

`bincoin init` creates the AI's own key, saves it in `~/.bincoin/agent.env` (readable by you only) and prints the
**AI address**. The key is never printed.

1. Open the dApp → **Agents**, choose how the AI plays and paste the AI address:
   - **Let an AI play my account**: you keep your wallet; the AI gets a key that can only play, with a BIN spending cap and an end date.
   - **Create a new AI miner**: an NFT with its own wallet and facility; the AI plays it within a daily budget you set.
2. Send a little ETH **for gas** to the AI address (0.001 ETH lasts thousands of moves on Robinhood Chain).
3. Run the two commands the dApp shows at the end, for example:

```bash
bincoin init --mode delegate --player 0xYourWallet
bincoin auto
```

That's it: your AI is mining, and you can watch it walk around your facility in the dApp.

## Commands

| Command | What it does |
|---|---|
| `bincoin init [--mode self\|delegate\|tba] [--player 0x…] [--chain 46630\|4663]` | Create (or keep) the AI key and save the settings |
| `bincoin address` | Print the AI address |
| `bincoin status [--json]` | What the AI sees: facility, miners, rewards, gas left |
| `bincoin plan` | What the strategy would do now, with reasons (no transaction) |
| `bincoin auto [--interval 300] [--dry-run] [--once] [--allow-eth]` | Play forever |
| `bincoin join [referrer]` · `claim` · `buy <typeId> [x y]` · `upgrade` · `sell <minerId>` | Single moves |

Strategy options for `plan` and `auto`: `--min-claim`, `--reserve`, `--max-payback` (days, default 120), `--allow-eth`
(let it spend ETH on the USD-priced facility tiers).

## Modes

| Mode | The AI key is… | `BINCOIN_PLAYER` |
|---|---|---|
| `self` | the player itself (it joins and pays with its own ETH) | not needed |
| `delegate` | an operator you authorised from your wallet (Agents → *Let an AI play my account*) | your wallet |
| `tba` | the operator of an NFT agent wallet (Agents → *Create a new AI miner* or *Use an NFT I already own*) | the agent wallet |

## Use it from Claude (MCP)

After `bincoin init`, the server reads its settings from `~/.bincoin/agent.env`:

```bash
claude mcp add bincoin -- bincoin-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{ "mcpServers": { "bincoin": { "command": "bincoin-mcp" } } }
```

Tools: `bincoin_status`, `bincoin_plan`, `bincoin_auto_step`, `bincoin_claim`, `bincoin_buy_miner`,
`bincoin_upgrade_facility`, `bincoin_sell_miner`, `bincoin_join`, `bincoin_rules`. See [SKILL.md](SKILL.md) for how
to play well.

## Settings

Environment variables override `~/.bincoin/agent.env` (and a `.env` in the current folder):

| Variable | Meaning |
|---|---|
| `BINCOIN_PRIVATE_KEY` | the AI's own key (created by `bincoin init`) |
| `BINCOIN_CHAIN_ID` | `46630` testnet (default), `4663` mainnet |
| `BINCOIN_MODE` | `self`, `delegate` or `tba` |
| `BINCOIN_PLAYER` | your wallet (`delegate`) or the agent wallet (`tba`) |
| `BINCOIN_RPC_URL` | optional custom RPC |
| `BINCOIN_DEPLOYMENTS` | optional path to a deployments JSON (the package ships the official addresses) |
| `BINCOIN_ENV_FILE` | optional other place for the settings file |

## Safety

- In `delegate` and `tba` modes the AI key is **sandboxed on-chain**: it can only play (claim, buy, install, upgrade,
  redeem). It can never move funds out.
- What it can spend is capped: the delegation's BIN cap and end date, or the agent wallet's daily BIN/ETH budget.
  You can stop it from the dApp at any time.
- Keep `~/.bincoin/agent.env` private and give the AI key only the ETH it needs for gas.

## Not affiliated

BinCoin is an independent community project built on Robinhood Chain, not affiliated with or endorsed by Robinhood
Markets. Play with amounts you can afford to lose.

## License

MIT, see [LICENSE](LICENSE).