> ## Documentation Index
> Fetch the complete documentation index at: https://docs.silvana.one/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Trade in the Grid Mode

Grid trading mode maintains a structured set of limit orders above and below a moving reference price, effectively creating a liquidity ladder that adapts to market conditions.

The agent continuously updates this grid: it tracks the reference price, places orders at predefined levels, and rebuilds the structure when orders are filled or the market shifts.

<Note>
  Prices are aligned to tick size, and the system can operate on one side only if the balance is limited.
</Note>

This setup lets you:

* automate market making without manual rebalancing;
* capture spread and micro price movements consistently;
* stay active in the market with controlled risk and sizing;
* avoid stale orders through automatic refresh and reset logic.

# Prerequisites

To participate in grid trading, you need to meet the following requirements:

* have Rust (stable) and `protoc` (protobuf compiler);
* build the Silvana Book agent CLI: `cargo build --release -p orderbook-cloud-agent` (run `target/release/cloud-agent`);
* have the Orderbook gRPC endpoint URL from Silvana;
* pass one-time onboarding: `cloud-agent onboard --rpc <URL>` (writes/updates `.env`);
* have minimal runtime inputs (`agent.toml` + `configuration.toml`), and balances for bids/offers plus Canton Coin fee reserve (`AGENT_FEE_RESERVE_CC`).

<Note>
  The following links are **necessary** for developers to access the protocol, library interface, and reference implementation:

  * [**Proto specification**](https://github.com/SilvanaOne/silvana-book-agent/tree/main/proto/silvana)
  * [**NPM library**](https://www.npmjs.com/package/@silvana-one/orderbook)
  * [**Agent code repository**](https://github.com/SilvanaOne/silvana-book-agent)
</Note>

**You’re recommended to:**

* complete [Agent Onboarding](/sdk/reference/agent-onboarding) (transport, auth, streaming basics);
* read the [Buy\&Sell Guide](/silvana-book/for-agent-developers/how-to-buy-and-sell-assets) (side mapping, base/quote semantics);
* have a safe space for secrets (JWTs, Ed25519 private keys if you use `signature`/`nonce`).

# Grid Mode Trading

Follow these steps to start trading in the grid mode.

## Step 1. Choose a market and confirm tick/size constraints

1.1. Obtain a `market_id` (e.g., from your environment, from `OrderbookService.GetMarkets`, or from Silvana support).

1.2. Confirm minimum order size, tick size, and any market-specific rules.

Grid mode is sensitive to tick size because prices are rounded before submission.

## Step 2. Ensure balances and fee reserve are in place

2.1. Check balances:

```javascript theme={null}
cloud-agent info balance
```

2.2. Before placing grid orders, ensure:

* **CC reserve:** unlocked CC \ge `AGENT_FEE_RESERVE_CC`
* **Bid-side liquidity:** enough unlocked quote to cover the sum of all bid levels
* **Offer-side liquidity:** enough unlocked base to cover the sum of all offer levels

If only one side is affordable, the agent will place a **partial grid** for that side.

## Step 3. Configure `agent.toml` for grid levels

Add a `[[markets]]` entry with bid/offer levels.

Example for `CBTC-CC` with 3 levels per side:

```javascript theme={null}
role = "agent"
auto_settle = true

# Update/refresh cadence (seconds)
poll_interval_secs = 5

[[markets]]
market_id = "CBTC-CC"
enabled = true

# Refresh the grid when the reference price moves by this percentage (absolute change)
price_change_threshold_percent = 0.5

# Bids (below reference): use negative deltas
[[markets.bid_levels]]
delta_percent = -0.5
quantity = "0.001"

[[markets.bid_levels]]
delta_percent = -1.0
quantity = "0.002"

[[markets.bid_levels]]
delta_percent = -2.0
quantity = "0.005"

# Offers (above reference): use positive deltas
[[markets.offer_levels]]
delta_percent = 0.5
quantity = "0.001"

[[markets.offer_levels]]
delta_percent = 1.0
quantity = "0.002"

[[markets.offer_levels]]
delta_percent = 2.0
quantity = "0.005"
```

## Step 4. Run the agent in grid mode

4.1. For grid-only operation:

```text theme={null}
cloud-agent agent --orders-only
```

4.2. For full LP operation (grid + settlement + optional RFQ, if configured):

```text theme={null}
cloud-agent agent
```

<Tip>
  Useful flags:

  * `--config \<PATH\>`: point to a specific `agent.toml`
  * `--dry-run`: prepare/verify transactions without signing/executing
  * `--verbose`: enable more logging
</Tip>

## Step 5. Validate placement and refresh behavior

On startup, expect the agent to **cancel existing active orders** and then place the configured grid.

During operation, expect refreshes when:

* price moves beyond `price\_change\_threshold\_percent`;
* partial fills occur (the agent cancels and re-places at the full configured quantity);
* orders go missing (filled/cancelled externally), detected when the active count drops below the expected level.

<Check>
  Congratulations! If you see orders placed at the expected number of levels (and occasional refreshes under the conditions above), **your grid is live**.
</Check>

# Tuning guidance

Follow these recommendations for a better trading experience.

1. **Level spacing (`delta_percent`)**:

* tighter levels improve fill probability but increase adverse selection risk;
* wider levels reduce churn and risk, but may quote less competitively.

2. **Per-level size (`quantity`)**:

* use a size you can repeatedly replenish (inventory will drift as one side fills);
* keep sizes consistent with your risk limits and market depth.

3. **Refresh threshold (`price_change_threshold_percent`)**:

* too low → frequent cancel/replace churn (more fees, more operational noise;
* too high → stale quotes (you may get picked off on fast moves).

4. **Polling cadence (`poll_interval_secs`)**:

* lower values respond faster but increase RPC load and churn;
* higher values are cheaper/slower; pair with a sensible refresh threshold.

# Common pitfalls to avoid

| Issue                                  | What to check / fix                                                                                                                                          |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| No orders placed                       | • ensure `market_enabled = true`; <br /> • verify you’re using a valid `market_id`; <br /> • check that balances are available and unlocked.                 |
| Only one side is live                  | • the agent may not have enough balance for the other side; <br /> • check `AGENT_FEE_RESERVE_CC` and available unlocked Canton Coins.                       |
| Orders appear “too close” or “too far” | • account for tick rounding (bids round down, offers round up); <br /> • verify `delta_percent` sign (negative for bids, positive for offers).               |
| Orders churn constantly                | • increase `price_change_threshold_percent`; <br /> • increase `poll_interval_secs`; <br /> • reduce the number of levels or tighten operational tolerances. |