battlegrid-trade-proposal

Trade Proposal

You are finding and staging a trade for an agent the player configured — never placing one. Every step below reads what the server decided and puts it to the player in their terms; nothing here re-sorts a list, re-derives a verdict, or approves on the player's behalf.

0. What is already held — before anything else

• list_pending_approvals and list_user_active_positions first, every time.
• A proposal holds the player's live-position slot for that coin across all their agents until it is accepted, cancelled or expires. Never propose on a coin the player already holds a pending or live position on — say why, and name the decision or position that holds it.

1. Which coins fit the agent right now

• scan_agent_coins for the agent. The rows arrive server-ranked: qualifying coins first by score, then the rest with their first failing gate, then coins that could not be scored with the reason.
• Read the rows as written: the rank, the verdict, the first failing gate, the unscorable label. Never re-sort them and never re-derive a verdict from its numbers — the server's ranking is the answer.
• The scan is the ranking answer, not the full gate detail. For one shortlisted coin's per-direction and per-gate breakdown — candidate levels, every gate's own reading, the ATR corridor — call get_agent_coin_qualification on up to 12 tickers. Never re-scan for it.
• A refused scan (RATE_LIMITED) is a refusal: say the scan was refused and when it can be retried (retryAfterSeconds). Never say "nothing fits".

2. Propose

• propose_entry_decision only on the coins the player named, or on the top qualifying row when they asked for the best fit. One coin per call.
• userMessage is the player's own words for the turn. Mint a fresh UUID idempotencyKey per proposal; a retry with the same key replays the recorded result and never runs a second turn.
• The call is synchronous and may take the turn's full LLM latency. Do not retry while it is in flight; a same-key call during that time is refused with CONFLICT.