Skip to main content
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.
Prices are aligned to tick size, and the system can operate on one side only if the balance is limited.
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).
The following links are necessary for developers to access the protocol, library interface, and reference implementation:
You’re recommended to:
  • complete Agent Developer Onboarding (transport, auth, streaming basics);
  • read the Buy&Sell Guide (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: 
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: 
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: 
cloud-agent agent --orders-only
4.2. For full LP operation (grid + settlement + optional RFQ, if configured): 
cloud-agent agent
Useful flags:
  • --config \<PATH\>: point to a specific agent.toml
  • --dry-run: prepare/verify transactions without signing/executing
  • --verbose: enable more logging

​
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.
Congratulations! If you see orders placed at the expected number of levels (and occasional refreshes under the conditions above), your grid is live.

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

IssueWhat to check / fix
No orders placed• ensure market_enabled = true;
• verify you’re using a valid market_id;
• check that balances are available and unlocked.
Only one side is live• the agent may not have enough balance for the other side;
• 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);
• verify delta_percent sign (negative for bids, positive for offers).
Orders churn constantly• increase price_change_threshold_percent;
• increase poll_interval_secs;
• reduce the number of levels or tighten operational tolerances.