API Keys

Bootstrap first API key via Bearer JWT (advanced / headless)

Create your first API key using a Supabase Bearer access token. Most users don’t call this endpoint directly — the dashboard at polysimulator.com/api-keys handles the JWT exchange transparently.

This endpoint exists for headless / CI setups where there’s no browser session: POST /v1/keys requires an existing X-API-Key, but a fresh user has no key yet.

Auth: Authorization: Bearer <supabase_access_token> from a programmatic Supabase sign-in. Verified HS256 against SUPABASE_JWT_SECRET with audience="authenticated"; expiry and sub UUID enforced.

Limits: 1 call/minute, 5 calls/hour per IP — real users only bootstrap once per account. Returns 400 BOOTSTRAP_NOT_ALLOWED if you already have API key(s); use POST /v1/keys for additional keys.

POST

keys

bootstrap

Bootstrap first API key via Bearer JWT (advanced / headless)

curl --request POST \
  --url https://api.polysimulator.com/v1/keys/bootstrap \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "default_magic": 4611686018427388000,
  "default_magic_label": "<string>",
  "name": "<string>",
  "tier": "<string>",
  "permissions": [
    "<string>"
  ]
}
'

import requests

url = "https://api.polysimulator.com/v1/keys/bootstrap"

payload = {
    "default_magic": 4611686018427388000,
    "default_magic_label": "<string>",
    "name": "<string>",
    "tier": "<string>",
    "permissions": ["<string>"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    default_magic: 4611686018427388000,
    default_magic_label: '<string>',
    name: '<string>',
    tier: '<string>',
    permissions: ['<string>']
  })
};

fetch('https://api.polysimulator.com/v1/keys/bootstrap', 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.polysimulator.com/v1/keys/bootstrap",
  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([
    'default_magic' => 4611686018427388000,
    'default_magic_label' => '<string>',
    'name' => '<string>',
    'tier' => '<string>',
    'permissions' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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.polysimulator.com/v1/keys/bootstrap"

	payload := strings.NewReader("{\n  \"default_magic\": 4611686018427388000,\n  \"default_magic_label\": \"<string>\",\n  \"name\": \"<string>\",\n  \"tier\": \"<string>\",\n  \"permissions\": [\n    \"<string>\"\n  ]\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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.polysimulator.com/v1/keys/bootstrap")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"default_magic\": 4611686018427388000,\n  \"default_magic_label\": \"<string>\",\n  \"name\": \"<string>\",\n  \"tier\": \"<string>\",\n  \"permissions\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/keys/bootstrap")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"default_magic\": 4611686018427388000,\n  \"default_magic_label\": \"<string>\",\n  \"name\": \"<string>\",\n  \"tier\": \"<string>\",\n  \"permissions\": [\n    \"<string>\"\n  ]\n}"

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

{
  "id": 123,
  "raw_key": "<string>",
  "key_prefix": "<string>",
  "rate_limit_tier": "<string>",
  "permissions": [
    "<string>"
  ],
  "created_at": "<string>",
  "name": "<string>",
  "default_magic": 123,
  "default_magic_label": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

authorization

string | null

Body

application/json

default_magic

integer | null

Magic number (0..9223372036854775807) stamped on every order placed with this key that does not send its own magic. Give each bot its own key to tag its orders without code changes.

Required range: 0 <= x <= 9223372036854776000

default_magic_label

string | null

Bot label (max 32 printable characters) stamped on every order placed with this key that does not send its own magic_label.

Maximum string length: 32

name

string | null

Human-readable label

Maximum string length: 100

tier

string | null

Rate limit tier: free, pro, pro_plus, enterprise. Defaults to the tier your subscription or grant entitles you to. May be set lower than your entitlement; higher is refused.

permissions

string[] | null

Permissions: read, trade, admin

Response

Successful Response

Returned once on creation — the raw key is NOT stored.

integer

required

raw_key

string

required

key_prefix

string

required

rate_limit_tier

string

required

permissions

string[]

required

created_at

string

required

name

string | null

default_magic

integer | null

Magic number (0..9223372036854775807) stamped on every order placed with this key that does not send its own magic. Give each bot its own key to tag its orders without code changes.

default_magic_label

string | null

Bot label (max 32 printable characters) stamped on every order placed with this key that does not send its own magic_label.

Bootstrap first API key via Bearer JWT (advanced / headless)

curl --request POST \
  --url https://api.polysimulator.com/v1/keys/bootstrap \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "default_magic": 4611686018427388000,
  "default_magic_label": "<string>",
  "name": "<string>",
  "tier": "<string>",
  "permissions": [
    "<string>"
  ]
}
'

import requests

url = "https://api.polysimulator.com/v1/keys/bootstrap"

payload = {
    "default_magic": 4611686018427388000,
    "default_magic_label": "<string>",
    "name": "<string>",
    "tier": "<string>",
    "permissions": ["<string>"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    default_magic: 4611686018427388000,
    default_magic_label: '<string>',
    name: '<string>',
    tier: '<string>',
    permissions: ['<string>']
  })
};

fetch('https://api.polysimulator.com/v1/keys/bootstrap', 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.polysimulator.com/v1/keys/bootstrap",
  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([
    'default_magic' => 4611686018427388000,
    'default_magic_label' => '<string>',
    'name' => '<string>',
    'tier' => '<string>',
    'permissions' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$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.polysimulator.com/v1/keys/bootstrap"

	payload := strings.NewReader("{\n  \"default_magic\": 4611686018427388000,\n  \"default_magic_label\": \"<string>\",\n  \"name\": \"<string>\",\n  \"tier\": \"<string>\",\n  \"permissions\": [\n    \"<string>\"\n  ]\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	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.polysimulator.com/v1/keys/bootstrap")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"default_magic\": 4611686018427388000,\n  \"default_magic_label\": \"<string>\",\n  \"name\": \"<string>\",\n  \"tier\": \"<string>\",\n  \"permissions\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/keys/bootstrap")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"default_magic\": 4611686018427388000,\n  \"default_magic_label\": \"<string>\",\n  \"name\": \"<string>\",\n  \"tier\": \"<string>\",\n  \"permissions\": [\n    \"<string>\"\n  ]\n}"

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

{
  "id": 123,
  "raw_key": "<string>",
  "key_prefix": "<string>",
  "rate_limit_tier": "<string>",
  "permissions": [
    "<string>"
  ],
  "created_at": "<string>",
  "name": "<string>",
  "default_magic": 123,
  "default_magic_label": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Overview

Endpoints

Bootstrap first API key via Bearer JWT (advanced / headless)

Authorizations

Headers

Body

Response