# Trade a specified token

Use the supplied token contract address. Run `inspect token --config CONFIG --input token.json` with `{"token":"0x..."}` to verify the protocol record, token name, symbol, and pool. This tool checks that the token belongs to the configured protocol. There is no token search. `poolState` provides token ordering, decimals, tick, tick spacing, and current square-root price. `balances.tokenBalance` is the connected wallet's raw token balance; use it directly for an authorized full-balance sale. `balances.wbnbBalance` is its raw WBNB balance.

`fairLaunch` in token inspection and buy quotes reports `active`, `endBlock`, `cumulativeBuyLimit`, `cumulativeBought`, and `remainingBuyAmount` in raw token units. The period uses block numbers: 192,000 blocks, about 24 hours on BSC. Each wallet's ordinary pool buys of the same token share a cumulative 0.2% supply allowance. The Creator's launch-transaction first buy has its own 2% cap; later Creator buys use the ordinary allowance. Sells and transfers do not restore used allowance. The ordinary buy allowance applies from token launch through the last protected block. After that, the temporary cap ends and Agent ID requirements continue. `maxWalletLimit` is a legacy alias for this amount, not a holding cap.

Recommend 0.01 BNB for an ordinary buy, or 0.001 BNB for a small buy. Use a budget specified by user intent or an already authorized strategy. The token share for that budget changes with price. First quote, then check the remaining cumulative allowance. The tool rejects a quote above it before creating wrap or approve steps; ask for a smaller budget or follow an already authorized sizing strategy. Do not silently trim the requested amount. Preview and execute simulate the current step again; the contract enforces the final amount at settlement.

All `amountIn` values are **raw integer strings**, not decimal token amounts. BNB and WBNB use 18 decimals. For the project token, match its address to `poolState.token0` or `token1` and use the corresponding `decimals0` or `decimals1`. Convert decimal amounts with `ethers.parseEther` or `ethers.parseUnits`, then `.toString()`; never multiply JavaScript floating point values.

Buy input (`buy.json`; replace `token` with the real address):

```json
{"token":"0x...","amountIn":"10000000000000000","source":"BNB","slippageBps":100}
```

This spends up to 0.01 BNB worth of WBNB input, using any existing WBNB first. `source:"BNB"` wraps only the WBNB shortfall; `source:"WBNB"` does not wrap. Explain this funding behavior when the user specifies which balance to use. The tool adds approvals only when needed, then swaps through the protocol router.

Sell input (`sell.json`):

```json
{"token":"0x...","amountIn":"1000000000000000000","receive":"BNB","slippageBps":100}
```

This sells 1 token if that token has 18 decimals. Default `receive` is `WBNB`. `receive:"BNB"` adds a separate withdrawal from WBNB after the swap; the tool updates it to the actual confirmed swap output.

From the package root, run the chosen action and the shared step loop:

```sh
node bin/agenticpad.cjs prepare buy --config /absolute/deployment.json --input /absolute/buy.json --out /absolute/buy.operation.json
node bin/agenticpad.cjs preview --config /absolute/deployment.json --operation /absolute/buy.operation.json
node bin/agenticpad.cjs execute --config /absolute/deployment.json --operation /absolute/buy.operation.json
```

For selling use `prepare sell` with `sell.json` and a separate operation file. After each confirmed step, preview and execute the next step in the same file. Funding and approvals are individual transactions; a confirmed approval alone does not complete the trade. A swap can complete while the final BNB withdrawal is still pending.

The quote contains `amountIn`, `amountOut`, `minimumOutput`, `tokenIn`, `tokenOut`, and `pool`. Confirmed `result.swap` contains actual `amountIn`, `amountOut`, both asset addresses, and `txHash`. Use actual result amounts when reporting settlement. If a quote expires, refresh the remaining business action only after resolving all prior submitted steps; existing wrapped funds and approvals remain on chain.