Skip to main content
A read key sees 12 tools. A read + write key sees those plus six more — three previews and the three actions they authorize. Tool results carry the same JSON as the corresponding REST endpoint, linked from each page.

​
Read tools

Available to every key. All are annotated readOnlyHint and count against the read window only.

​
Discover topics

​
Inspect one topic

​
The key owner’s account

Balances exist only on get_my_profile and the other *_my_* tools — public profiles never expose another user’s holdings.

​
Write tools

Only on keys created with the write scope; a read-only key never sees them. Every action is two steps — preview, then execute — and the execute tool accepts only the confirm_token its preview minted. See Write actions & confirmation. The three previews count against the read window only. The three executing tools additionally consume the write window (10/min, 200/day).
Annotations are hints a client may or may not act on — they are not the safeguard. The safeguard is that an execute tool takes nothing but a confirm_token, so the summary always exists before the action does. Showing that summary to the user and getting a real confirmation is still your job.
There is no tool to sell a position — selling is only available in the SeeSaw app. Positions sold there show up in list_my_positions as sold: true.

​
Typical combinations

  • “What does the market think about X?” — search_topics → get_topic → list_topic_opinions.
  • “Summarize the debate” — get_topic → list_topic_opinions (each opinion’s side makes sentiment directly readable).
  • “How am I doing?” — get_my_profile → list_my_positions → list_my_coin_ledger / list_my_ruby_ledger.
  • “Put 300 coins on Yes” — get_topic (check stake_rules) → preview_order with amount_coins: 300 → user confirms → place_order. If the user names no amount, ask for one before previewing.
  • “Support that take” — list_topic_opinions → preview_back → user confirms → back_opinion.