Preview an order at the user's stake (step 1 of 2)

curl --request POST \
  --url https://api.seesaw.fun/open/v1/topics/{id}/order-preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "option_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount_coins": 300
}
'

import requests

url = "https://api.seesaw.fun/open/v1/topics/{id}/order-preview"

payload = {
    "option_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "amount_coins": 300
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({option_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', amount_coins: 300})
};

fetch('https://api.seesaw.fun/open/v1/topics/{id}/order-preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.seesaw.fun/open/v1/topics/{id}/order-preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'option_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'amount_coins' => 300
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.seesaw.fun/open/v1/topics/{id}/order-preview"

	payload := strings.NewReader("{\n  \"option_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount_coins\": 300\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.seesaw.fun/open/v1/topics/{id}/order-preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"option_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount_coins\": 300\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.seesaw.fun/open/v1/topics/{id}/order-preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"option_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount_coins\": 300\n}"

response = http.request(request)
puts response.read_body

{
  "can_place": true,
  "summary": {
    "topic_title": "<string>",
    "option_label": "<string>",
    "stake_coins": "<string>",
    "balance_before": "<string>",
    "balance_after": "<string>",
    "price_now": "<string>",
    "price_after": "<string>",
    "payout_if_correct_rubies": "<string>",
    "ruby_multiplier": "1.0000",
    "avg_price": "<string>",
    "close_time": "2023-11-07T05:31:56Z",
    "mechanism": "<string>"
  },
  "reason": "TOPIC_CLOSED",
  "details": {
    "min_coins": "500.0000",
    "max_coins": "1000.0000"
  },
  "confirm_token": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

Trading

Preview an order at the user's stake (step 1 of 2)

Computes the summary the user must confirm and, when the order is currently possible, mints a confirm_token for POST /orders. Charges nothing. Requires the write scope; counts against the read window only.

The stake is the user’s choice. If the user stated how many coins to stake, send exactly that as amount_coins; if they did not, ask them before calling — never choose, infer or round an amount on their behalf. The allowed range is the topic’s stake_rules (min_coins..max_coins, whole coins, from GET /topics/{id}).

When can_place is false the reason says why and no token is issued:

STAKE_OUT_OF_RANGE — amount_coins is outside the range. TOPIC_CLOSED and ALREADY_STAKED take precedence over it (the reason is then one of those and details is absent, while the summary keeps the shape described here); it takes precedence over INSUFFICIENT_BALANCE. details carries min_coins / max_coins, summary.stake_coins echoes the requested amount (it is not clamped), balance_after equals balance_before, price_now is the current display price, and price_after, payout_if_correct_rubies, ruby_multiplier and avg_price are empty strings.
MECHANISM_UNSUPPORTED (a v2_share topic) — the summary is partial: only topic_title, option_label, stake_coins, the balances, price_now, close_time and mechanism are meaningful.
ALREADY_STAKED — the owner already placed this topic’s one order, including an order they have since sold in the app.
INSUFFICIENT_BALANCE — the balance is below stake_coins.

The stake is bound into the token: a different amount needs a new preview, and POST /orders spends exactly the previewed stake_coins.

POST

topics

{id}

order-preview

Preview an order at the user's stake (step 1 of 2)

curl --request POST \
  --url https://api.seesaw.fun/open/v1/topics/{id}/order-preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "option_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount_coins": 300
}
'

import requests

url = "https://api.seesaw.fun/open/v1/topics/{id}/order-preview"

payload = {
    "option_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "amount_coins": 300
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({option_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', amount_coins: 300})
};

fetch('https://api.seesaw.fun/open/v1/topics/{id}/order-preview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.seesaw.fun/open/v1/topics/{id}/order-preview",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'option_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'amount_coins' => 300
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.seesaw.fun/open/v1/topics/{id}/order-preview"

	payload := strings.NewReader("{\n  \"option_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount_coins\": 300\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.seesaw.fun/open/v1/topics/{id}/order-preview")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"option_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount_coins\": 300\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.seesaw.fun/open/v1/topics/{id}/order-preview")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"option_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"amount_coins\": 300\n}"

response = http.request(request)
puts response.read_body

{
  "can_place": true,
  "summary": {
    "topic_title": "<string>",
    "option_label": "<string>",
    "stake_coins": "<string>",
    "balance_before": "<string>",
    "balance_after": "<string>",
    "price_now": "<string>",
    "price_after": "<string>",
    "payout_if_correct_rubies": "<string>",
    "ruby_multiplier": "1.0000",
    "avg_price": "<string>",
    "close_time": "2023-11-07T05:31:56Z",
    "mechanism": "<string>"
  },
  "reason": "TOPIC_CLOSED",
  "details": {
    "min_coins": "500.0000",
    "max_coins": "1000.0000"
  },
  "confirm_token": "<string>",
  "expires_at": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Personal API key issued per SeeSaw user account: Authorization: Bearer sspat_…. Manage keys on the app API (/v1/users/me/api-keys). Revocation propagates within ~60 seconds (validation cache window).

The key's scopes decide what it may do: every key has read; a key created with ["read","write"] may also use the six write operations (marked x-required-scope: write in this document). Scopes are fixed at creation — to get write access, create a new key. A read-only key calling a write operation gets 403 FORBIDDEN_SCOPE.

Path Parameters

string<uuid>

required

Topic UUID.

Body

application/json

option_id

string<uuid>

required

The option to stake on, from the topic's options.

amount_coins

integer

Coins to stake — a whole number within the topic's stake_rules (min_coins..max_coins). Pass the amount the user stated; if they did not state one, ask them first. Outside the range: 200 with can_place: false and reason STAKE_OUT_OF_RANGE (never adjusted). Must be a JSON integer: a quoted string such as "100", a fraction, zero or a negative number is 400 INVALID_ARGUMENT with details.field = amount_coins. Omitted: the order stakes stake_rules.default_coins — a fallback, not a recommendation.

Required range: x >= 1

Example:

300

Response

The preview (check can_place before confirming)

can_place

boolean

required

summary

object

required

What the user confirms before POST /orders. stake_coins is what the order spends; payout_if_correct_rubies is the rubies received if the option wins — units × ruby_multiplier, so it differs from the unit count while a ruby boost runs. It is a guaranteed minimum: if the topic settles while a ruby boost is live, it pays at the higher multiplier. The stake is not returned.

Show child attributes

reason

enum<string>

Present only when can_place is false.

Available options:

TOPIC_CLOSED,

ALREADY_STAKED,

INSUFFICIENT_BALANCE,

MECHANISM_UNSUPPORTED,

STAKE_OUT_OF_RANGE

details

object

Present only with STAKE_OUT_OF_RANGE — the topic's stake range.

Show child attributes

confirm_token

string

Present only when can_place is true.

expires_at

string<date-time>

Present only when can_place is true. 5 minutes out.

REST API

Endpoints

Preview an order at the user's stake (step 1 of 2)

Authorizations

Path Parameters

Body

Response