API pública do Spiro Land

1. 01Crie a chave

   O dono do servidor cria a chave em Onde fica:Integrações›, API, no painel no site. A API faz parte do plano Elder, e o texto da chave aparece uma vez só.

2. 02Confira a chave

   GET /v1/me responde quem é a chave, de qual servidor, e se a API está aberta para ela. É a chamada certa para testar uma chave nova.

   curlCopiar

   curl https://spiro.land/api/v1/me \
     -H "Authorization: Bearer $SPIRO_LAND_KEY"

3. 03Veja se está pronta

   JSONCopiar

   {
     "key": {
       "id": "key_8fK2mQ1xZp0a",
       "name": "Community site",
       "type": "secret",
       "prefix": "sl_sec_Ab3x…9QzT",
       "scopes": ["killfeed:read", "leaderboard:read"],
       "expiresAt": null
     },
     "server": { "name": "My Evrima Server", "panelOnline": true, "panelVersion": "0.1.52" },
     "api": { "status": "ready" },
     "limits": { "perMinute": 120 }
   }

   O campo api.status diz o que falta, em vez de um erro seco:

   ready

   Tudo pronto. Os endpoints do plano respondem.

   panelNotReady

   O painel do servidor ainda não roda ordens da API. O dono atualiza o painel, ou espera a renovação da licença, que leva até 24 h.

   notInPlan

   O plano do servidor não inclui a API.

   suspended

   O Spiro Land suspendeu a API deste servidor. O dono vê o motivo em Onde fica:Integrações›, API.

Passo a passo: Ligar o site da comunidade com a API

Toda chamada leva a chave no cabeçalho Authorization: Bearer <key>. Nunca na URL: uma chave na query é recusada com 400 keyInUrl, porque a URL fica gravada nos registros do proxy e no histórico do navegador.

A trava de domínio impede que outro site use a sua chave pública no navegador de um visitante. Ela não impede um script de servidor que forje o cabeçalho Origin, e é por isso que a chave pública só alcança dado que já é público no jogo.

Toda resposta diz quanto sobra no minuto:

RateLimit-Limit

o teto da chave por minuto

RateLimit-Remaining

quantos pedidos ainda cabem

RateLimit-Reset

em quantos segundos a conta recomeça

Passou do teto, a resposta é 429 rateLimited com Retry-After em segundos. Espere esse tempo antes de tentar de novo.

Um IP que erra a chave 30 vezes num minuto recebe 429 até o minuto virar, antes mesmo de a chave ser conferida.

O Spiro Land pode dar a uma chave um teto próprio. limits.perMinute em /v1/me mostra o que vale para a sua.

As leituras respondem da memória da central, com o que o painel do servidor mandou por último. asOf diz quando essa versão chegou, e stale fica verdadeiro quando o painel está sem sinal. Com o painel sem sinal, o que ninguém sabe sai null: se o servidor está ligado e quem está online.

Depois de um tempo sem ninguém consultar, a primeira leitura pede o dado ao painel e espera até 4 segundos por ele. Se não chegar, a resposta é 409 dataNotReady com Retry-After.

O cursor do kill feed

O kill feed vem da morte mais nova para a mais velha. Guarde o cursor da resposta e mande de volta em after: a próxima resposta traz só as mortes depois dele.

after

Só as mortes depois deste id. Sem ele, as mais recentes.

limit

De 1 a 100 mortes por resposta. O padrão é 50.

cursorReset

O painel foi reinstalado e os ids recomeçaram. Limpe a lista e recomece desta resposta.

gap

Houve mais mortes do que esta resposta traz, ou do que a central guarda (100). As do meio não vêm mais.

<ul id="feed"></ul>
<script>
  const KEY = "sl_pub_...";
  let cursor = null;

  async function update() {
    const url = new URL("https://spiro.land/api/v1/killfeed");
    if (cursor) url.searchParams.set("after", cursor);
    const r = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
    if (!r.ok) return;
    const feed = await r.json();
    const list = document.querySelector("#feed");
    if (feed.cursorReset) list.replaceChildren();
    for (const k of feed.kills.reverse()) {
      const li = document.createElement("li");
      li.textContent = `${k.killer?.name ?? "The island"} > ${k.victim.name ?? "Unknown survivor"} (${k.victim.species})`;
      list.prepend(li);
    }
    cursor = feed.cursor;
  }

  update();
  setInterval(update, 10000);
</script>

Um widget de kill feed inteiro, sem dependência, com a chave pública. Ele consulta a cada 10 segundos.

O que mexe no jogo vira uma ordem para o painel do servidor. A resposta espera o desfecho por até 8 segundos: 200 quando ele chega, ou 202 com Location quando o painel demora. Nesse caso, consulte a ordem até ela terminar.

Mande Idempotency-Key (de 1 a 64 letras, números, _ ou -) para repetir um pedido sem medo: a mesma chave acha a mesma ordem, e o jogo faz uma vez só. Onde mexe em moeda ou item ela é obrigatória. A mesma chave com outro corpo responde 409 idempotencyConflict. A chave vale enquanto a central guarda a ordem: até 30 dias, e menos num servidor com mais de 1.000 ordens encerradas nesse tempo. Depois disso, o mesmo pedido cria uma ordem nova: repita com a mesma chave só dentro desse prazo.

curl -X POST https://spiro.land/api/v1/players/76561198000000001/garage/park \
  -H "Authorization: Bearer $SPIRO_LAND_KEY" \
  -H "Idempotency-Key: park-76561198000000001-2026-09-25" \
  -H "Content-Type: application/json" \
  -d '{ "slot": "a" }'

Com o painel fora do ar nada é enfileirado, e a resposta é 409 panelOffline. Quando o painel recusa, a resposta é 409 refused, com o motivo em reason:

{
  "error": {
    "code": "refused",
    "message": "The server's panel refused this. The reason field says why.",
    "reason": "cooldown",
    "detail": "The player used the garage too recently.",
    "retryAfterMs": 90000,
    "order": "api_Zx81kQm2Lw0pE4tR9yB6nV3cH7sJ5aDf"
  }
}

garageClosed

O dono fechou a garagem.

cooldown

O jogador usou a garagem há pouco. retryAfterMs diz quanto falta.

insufficientFunds

O jogador não tem saldo para pagar. price e balance dizem quanto custa e quanto ele tem.

slotOccupied

Já há um dino nessa vaga.

garageFull

Todas as vagas que o jogador pode usar estão ocupadas.

slotNotAllowed

O jogador não tem direito a essa vaga pelos cargos dele.

slotChanged

O dino da vaga mudou desde a leitura. Leia a garagem de novo e mande a version nova.

speciesMismatch

O jogador está em outra espécie. Mande swap: true para trocar, sabendo que o dino atual some.

speciesNotPlayable

A troca de espécie ainda não chega a essa espécie. O jogador resgata entrando no jogo com ela, sem swap.

playerOffline

O jogador não está no jogo. Com target: true, é o jogador de destino que não está no jogo com um dino.

notLinked

O jogador ainda não tem carteira neste servidor. Abra a conta sem Discord pelo POST /v1/players/{steamId}/account, ou peça para ele vincular o Discord.

productNotFound

Não há produto com esse id na loja agora.

alreadyOwned

O jogador já tem essa pele para sempre.

itemNotFound

Esse item não está no inventário do jogador, ou já foi removido.

alreadyUnlimited

O item já é ilimitado.

noUsesLeft

O item não tem mais usos para tirar.

purchaseNotFound

Não há compra com esse id neste painel.

purchaseClosed

A compra já foi resolvida por outra pessoa.

refundFailed

O estorno não passou, e o jogador segue sem as moedas. Confira a carteira antes de tentar de novo.

inCombat

O jogador está em combate. Tente de novo em uns 20 segundos.

noDinosaur

O jogador está no jogo sem dino agora: morto, renascendo ou escolhendo a espécie. No slay, vale também para quem está fora do jogo.

invalidChoice

A escolha do grow não serve: falta mutação para um slot, ou uma é desconhecida, repetida ou fora do slot.

notEligible

O grow não serve para a espécie de agora. tiers traz as que servem.

notApplied

O jogo não aplicou (jogador offline, morto ou na seleção). O uso voltou para o item.

notUsable

Este item não se usa por este caminho (por exemplo, pedir as mutações de algo que não é grow), ou o painel do servidor é anterior ao uso da entrega manual e do dino do kit pelo site: atualize o painel.

linkConflict

O Discord já está vinculado a outra Steam neste servidor, ou a Steam a outro Discord. conflict diz qual dos dois. Nada mudou: desvincule antes, se o vínculo antigo estiver errado.

skinNotDrawn

A pele desse produto ainda está por desenhar. Ela não se vende; o carrinho de graça a entrega no painel 0.1.87 ou mais novo, e usar o item recusa sem gastar até o dono desenhar.

outOfStock

Um produto do carrinho esgotou. O estoque é um só para a loja do Discord, o /players e o seu site, no painel 0.1.89 ou mais novo. Vem com o productId; nada foi cobrado.

limitReached

O jogador já levou o máximo de um produto (o limite por jogador da loja). Vem com o productId; nada foi cobrado.

gameNotResponding

O jogo não deu uma resposta que se lesse: o mod não respondeu a tempo, o servidor ainda está subindo o mapa, ou a resposta chegou ilegível. Nada mudou; tente de novo em alguns segundos. As leituras do dino recusam assim no painel 0.1.91 ou mais novo; antes dele vinham como unknown, e o prime de quem estava fora do jogo como noDinosaur.

unknown

O painel recusou por outro motivo. detail traz a frase dele.

alreadyGrown

O dino já está no crescimento do grow ou acima dele, e usar não o faria crescer. growth traz o do item (0 a 1). Nada foi gasto.

closesPrime

O dino ainda não é prime, está abaixo de 75% e o grow, sem prime, o leva a 75% ou mais: o prime desse dino fecha. growth traz o do item (0 a 1). Explique ao jogador e mande acceptPrimeClose true se ele confirmar. Nada foi gasto.

giftsDisabled

A doação de itens está desligada neste servidor (Painel do jogador › Recursos). Nada foi doado.

notGiftable

Este item não se doa: kit inicial, grow grátis ou item que veio de outro servidor. Nada foi doado.

patternOutOfRange

O desenho pedido não existe nessa espécie, pela contagem medida no jogo de hoje. patterns traz quantos ela tem (os índices vão de 0 a patterns menos 1). Nada foi escrito no dino.

growthLimit

O dono ligou o limite de crescimento do teleporte de amigo, e quem vai (ou o amigo, com target) está no limite ou acima. growth traz o crescimento do dino e maxGrowth o limite, os dois de 0 a 1. Ninguém se moveu.

boughtSkin

O dino tem uma pele comprada na loja ou pelo inventário. Peça a confirmação do jogador e mande replaceBought true: a comprada não volta para esse dino. Nada foi pintado e o uso voltou.

O que mexe no jogo vira uma ordem, que o painel do servidor executa. GET /v1/orders/{id} mostra onde ela está. Cada chave só enxerga as próprias ordens: a de outra chave responde 404 orderNotFound, igual a uma que não existe.

A central guarda, por servidor, as 1.000 ordens encerradas mais novas, e nenhuma encerrada há mais de 30 dias. Uma ordem na fila ou rodando nunca sai. A que já saiu responde 404 orderNotFound, igual a uma que não existe.

{
  "order": {
    "id": "api_Zx81kQm2Lw0pE4tR9yB6nV3cH7sJ5aDf",
    "status": "done",
    "createdAt": "2026-09-25T18:04:11.000Z",
    "result": { "ok": true, "message": "Tyrannosaurus stored in slot 2.", "at": "2026-09-25T18:04:13.000Z" }
  }
}

pending

Na fila, esperando o painel buscar.

delivered

O painel levou e está executando.

done

Feita. result traz a mensagem do painel.

failed

O painel tentou e não deu. result diz por quê.

replaced

Uma ordem mais nova tomou o lugar desta antes de o painel buscá-la.

revoked

Cancelada antes de rodar, por exemplo porque a chave foi revogada.

O seu site descobre a conta Steam de quem está no navegador dele, confirmada pela própria Steam, sem o jogador entrar no spiro.land. Ele clica num botão do seu site, confirma na Steam (quase sempre já está logado lá) e volta para o seu site. O SteamID chega ao servidor do seu site pela exchange, e nunca pela URL.

Jogador        clica em "Verificar com a Steam" no seu site
   |
   ▼
Seu servidor   POST /v1/verifications { redirectUri, state }
   |           ← { verification: { id, url } }
   ▼
Navegador      vai para a url → spiro.land → Steam, e confirma lá
   |
   ▼
spiro.land     confere com a Steam e devolve o navegador para
   |           redirectUri?verification=…&state=…&code=…
   ▼
Seu servidor   confere o state da sessão e chama
   |           POST /v1/verifications/{id}/exchange { code }
   |           ← { player: { steamId, name, linked, discordId } }
   ▼
Seu site       guarda o SteamID na sessão do jogador

1. 01Ligue a permissão e cadastre a volta

   Em Onde fica:Integrações›, API, crie ou edite uma chave secreta, marque players:verify e escreva em Endereços de volta da verificação o endereço exato do seu site que recebe o jogador, como https://seusite.com/verificar/volta. A central só devolve o navegador a um endereço dessa lista, comparado por inteiro.

2. 02Comece pelo servidor do seu site

   Quando o jogador clicar, o servidor do seu site sorteia um state, guarda na sessão dele e chama POST /v1/verifications com o redirectUri e o state. A resposta traz verification.url: redirecione o navegador para ela. A chave secreta nunca vai ao navegador.

   JSONCopiar

   {
     "verification": {
       "id": "ver_Ab3xQ9mK2LwP7tRz",
       "status": "pending",
       "url": "https://spiro.land/api/v1/verifications/ver_Ab3xQ9mK2LwP7tRz/steam",
       "expiresAt": "2026-10-05T03:15:00.000Z"
     }
   }

3. 03Receba a volta

   O jogador volta ao seu redirectUri com verification, state e code, ou com error quando não deu certo. Compare o state com o da sessão e, se for diferente, descarte a volta: é isso que impede alguém de plantar no navegador de outra pessoa uma volta que não é dela.

   Copiar

   https://yoursite.com/verify/return
     ?verification=ver_Ab3xQ9mK2LwP7tRz
     &state=f3Kq9xLm2PwZ7tRb
     &code=Qm8xT2vLk9PzR4wN7cJ1yB5hD3sF6gA0eU8iO2pK4tY

4. 04Troque o código pelo SteamID

   Do servidor do seu site, chame POST /v1/verifications/{id}/exchange com o code. O player.steamId da resposta é a conta que a Steam confirmou: guarde na sessão e use nos outros endpoints. O código vale uma vez só, por cinco minutos.

   JSONCopiar

   {
     "verification": {
       "id": "ver_Ab3xQ9mK2LwP7tRz",
       "status": "exchanged",
       "method": "steam",
       "verifiedAt": "2026-10-05T03:01:12.000Z"
     },
     "player": {
       "steamId": "76561198000000001",
       "name": "Rex",
       "linked": true,
       "discordId": "100000000000000001"
     }
   }

   linked diz se o jogador já vinculou a conta ao Discord do seu servidor. Sem vínculo, abra a conta dele com POST /v1/players/{steamId}/account: ele ganha a carteira de moedas sem passar pelo Discord nem pelo spiro.land, e se vincular o Discord depois, a mesma carteira continua, com o saldo. null quer dizer que o painel ainda não mandou a lista: a verificação vale do mesmo jeito.

Se o seu site já tem login Steam próprio, a verificação não é necessária: o SteamID que a Steam devolveu ao seu login já está provado. Depois do login, chame POST /v1/players/{steamId}/account com uma chave secreta com link:write, e o jogador ganha a conta sem passar pelo Discord nem pelo spiro.land.

// Node 18+ (fetch and crypto are built in). SPIRO_LAND_KEY: a secret key with players:verify and link:write.
import { randomBytes } from "node:crypto";

const API = "https://spiro.land/api/v1";
const RETURN = "https://yoursite.com/verify/return"; // registered on the key
const headers = {
  Authorization: `Bearer ${process.env.SPIRO_LAND_KEY}`,
  "Content-Type": "application/json",
};

// 1. The player clicked "Verify with Steam": redirect the browser to the url this returns.
export async function startVerification(session) {
  session.verifyState = randomBytes(24).toString("base64url");
  const r = await fetch(`${API}/verifications`, {
    method: "POST",
    headers,
    body: JSON.stringify({ redirectUri: RETURN, state: session.verifyState }),
  });
  const body = await r.json();
  if (!r.ok) throw new Error(body.error.code);
  return body.verification.url;
}

// 2. The browser came back to RETURN. query: the parsed query string of that request.
export async function finishVerification(session, query) {
  const expected = session.verifyState;
  delete session.verifyState;
  if (!expected || query.state !== expected) throw new Error("state mismatch");
  if (query.error) throw new Error(query.error); // cancelled, refused, expired...

  const r = await fetch(`${API}/verifications/${encodeURIComponent(query.verification)}/exchange`, {
    method: "POST",
    headers,
    body: JSON.stringify({ code: query.code }),
  });
  const body = await r.json();
  if (!r.ok) throw new Error(body.error.code);
  session.steamId = body.player.steamId; // proven by Steam, never typed by the player

  // 3. No Discord link: open the account, so coins and time income work without Discord.
  if (body.player.linked === false) {
    await fetch(`${API}/players/${body.player.steamId}/account`, { method: "POST", headers });
  }
  return body.player;
}

Quando não dá certo, a volta traz error no lugar de code:

cancelled

O jogador desistiu na página da Steam.

refused

A Steam não confirmou a entrada, ou a volta não veio do mesmo navegador que começou. Comece de novo.

expired

Passou o prazo de 15 minutos para entrar na Steam. Comece de novo.

alreadyStarted

O endereço da verificação já tinha sido aberto (um recarregar ou o voltar do navegador). Crie outra.

alreadyUsed

Essa volta já foi usada. Crie outra verificação.

unavailable

A central não conseguiu falar com a Steam agora. Tente de novo em instantes.

Limites: a verificação vale 15 minutos até a volta da Steam; o código vale 5 minutos e uma troca; cinco códigos errados encerram a verificação; cada chave tem até 300 verificações abertas ao mesmo tempo (429 tooManyVerifications); e cada chamada conta no limite por minuto da chave.

Segurança

• O SteamID sai da Steam e da troca, nunca de algo que o navegador manda. Não aceite SteamID digitado nem lido da URL.
• A chave secreta e a troca ficam no servidor do seu site. Usada num navegador, a chave é recusada.
• Na página da Steam o jogador vê spiro.land: é o Spiro Land que confere com a Steam em nome do seu servidor. Ele não cria conta nem entra no spiro.land, e a Steam nunca entrega a senha a ninguém.
• Cada verificação é de uma chave: outra chave, mesmo do mesmo servidor, recebe 404 verificationNotFound.
• A central guarda só a impressão do código, por minutos, e na memória. Um reinício dela encerra as verificações abertas, e o jogador clica de novo.

Mostre no seu site onde o jogador está e onde está o grupo dele. Há dois jeitos: embutir o mapa pronto do spiro.land num iframe (o mesmo da aba Mapa do painel do jogador, com camadas, busca e zoom) ou desenhar o seu, com a imagem, as zonas e as posições que a API entrega. Nos dois, só aparecem o jogador e quem está no grupo dele naquele momento: ninguém de fora, nem como ponto.

Embutir o mapa

1. 01Dê a permissão e os sites

   Em Onde fica:Integrações›, API, numa chave secreta, marque map:read e liste em Sites que podem embutir o mapa os endereços do seu site, como https://seusite.com. O mapa só abre dentro deles.

2. 02Abra o embutido no seu servidor

   Quando o jogador abrir a página, o servidor do seu site chama POST /v1/players/{steamId}/map/embed com o SteamID de quem entrou no seu site (pela verificação ou pelo seu login Steam). Abra um por carga da página: ele vale enquanto alguém olha.

   JSONCopiar

   {
     "embed": {
       "id": "emb_Ab3xQ9mK2LwP7tRz",
       "url": "https://spiro.land/embed/map?id=emb_Ab3xQ9mK2LwP7tRz#Qm8xT2vLk9PzR4wN7cJ1yB5hD3sF6gA0eU8iO2pK4tY",
       "expiresAt": "2026-10-07T23:40:00.000Z"
     }
   }

3. 03Ponha a url num iframe

   Use embed.url como o src de um iframe. O mapa se ajusta à largura que você der: estreito, a busca, as camadas e o grupo vão para baixo do mapa.

   HTMLCopiar

   <iframe
     src="{embed.url}"
     title="Live map"
     style="width: 100%; height: 720px; border: 0"
   ></iframe>

O id vai na consulta e o segredo depois do #, que o navegador não manda a servidor nenhum; a página do mapa o tira do endereço ao abrir. O embutido vence depois de uma hora sem ninguém olhando, e em doze horas no máximo: vencido, o mapa pede para recarregar a página do seu site, que abre outro.

// Node 18+, no dependencies. Run:
//   SPIRO_LAND_KEY=sl_sec_... STEAM_ID=76561198000000001 node spiro-map-embed.mjs
// The key needs the Map permission, with http://localhost:3000 in its map websites.
import { createServer } from "node:http";

const API = "https://spiro.land/api/v1";

createServer(async (req, res) => {
  if (req.url !== "/") return res.writeHead(404).end();

  // On your site, STEAM_ID is the player who signed in (verification or your own Steam login).
  const r = await fetch(`${API}/players/${process.env.STEAM_ID}/map/embed`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.SPIRO_LAND_KEY}` },
  });
  const body = await r.json();
  if (!r.ok) return res.writeHead(r.status, { "Content-Type": "text/plain" }).end(body.error.code);

  // A new embed for every page load: it lasts while someone looks at it.
  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(`<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Live map</title>
<iframe src="${body.embed.url}" title="Live map" style="width:100%;height:90vh;border:0"></iframe>`);
}).listen(3000, () => console.log("Open http://localhost:3000"));

Baixar o exemplo pronto (spiro-map-embed.mjs) Rode com a sua chave secreta e um SteamID, e abra http://localhost:3000.

Desenhar o seu próprio mapa

GET /v1/map entrega tudo o que o seu mapa precisa, com a mesma chave secreta e a permissão map:read: os limites do Gateway em centímetros, as camadas da imagem com a versão de cada uma, os rótulos e as zonas.

{
  "map": "Gateway",
  "liveMap": true,
  "heat": true,
  "bounds": { "xMin": -505000, "xMax": 607000, "yMin": -607000, "yMax": 509000 },
  "image": { "width": 975, "height": 977, "contentType": "image/webp" },
  "layers": [
    { "id": "color", "path": "/v1/map/image?layer=color", "version": "3f9a1c0b7e2d", "bytes": 185456, "overlay": false },
    { "id": "gray", "path": "/v1/map/image?layer=gray", "version": "a81e44c09d15", "bytes": 138000, "overlay": false },
    { "id": "water", "path": "/v1/map/image?layer=water", "version": "5c02d9e7b3f8", "bytes": 22986, "overlay": true }
  ],
  "svg": { "viewBox": "-505 -607 1112 1116", "unitCm": 1000 },
  "labels": [
    { "kind": "region", "name": "Delta", "x": 177000, "y": 33000, "detail": 0 }
  ],
  "zones": [
    { "kind": "sanctuary", "name": "Delta side", "center": { "x": 228000, "y": -18000 },
      "path": "M217 -18A11 11 0 0 0 239 -18A11 11 0 0 0 217 -18Z" }
  ]
}

GET /v1/map/image?layer= devolve o WebP de 975 por 977 de uma camada: color, gray ou water (a água doce, transparente, para pôr por cima da cor). A imagem leva spiro.land num canto: mantenha a marca. Baixe pelo servidor do seu site uma vez por version e sirva do seu próprio endereço; a chave nunca vai ao navegador.

curl https://spiro.land/api/v1/map/image?layer=color \
  -H "Authorization: Bearer $SPIRO_LAND_KEY" \
  -o gateway-color.webp

A resposta traz a versão no ETag. Mande o mesmo valor em If-None-Match e, sem mudança, a resposta é 304, sem corpo. Mais simples ainda: compare o version de GET /v1/map com o que você guardou.

GET /v1/players/{steamId}/map devolve o jogador e o grupo dele, com nome, espécie e há quantos milissegundos a posição foi lida. A primeira leitura acorda o painel do servidor e volta 409 dataNotReady: leia de novo a cada 5 segundos enquanto a página estiver aberta. Sem dino em campo, player vem null.

{
  "map": "Gateway",
  "status": "ok",
  "groupsRead": true,
  "player": { "name": "Rex", "species": "Carnotaurus", "x": 12000, "y": -48000, "seenAgoMs": 2400 },
  "group": [
    { "name": "Ana", "species": "Tyrannosaurus", "x": 20000, "y": -40000, "seenAgoMs": 2400 }
  ],
  "asOf": "2026-10-07T22:40:03.000Z",
  "stale": false
}

x e y estão em centímetros do jogo, as mesmas coordenadas do teleporte, com precisão de dez metros. A conta abaixo leva ao pixel da imagem da API, com a origem no canto de cima à esquerda.

// bounds and image come from GET /v1/map. The origin is the top left corner.
function toPixel(x, y, bounds, image) {
  return {
    left: ((x - bounds.xMin) / (bounds.xMax - bounds.xMin)) * image.width,
    top: ((y - bounds.yMin) / (bounds.yMax - bounds.yMin)) * image.height,
  };
}

zones traz santuários, migração, patrulha e cavernas, e labels os nomes das regiões, águas e lugares. O path de cada zona é um desenho de SVG em unidades do mapa (dez metros): ponha num svg com o svg.viewBox por cima da imagem e ele cai no lugar. detail vai de 0 (aparece de longe) a 2 (só de perto).

<div style="position: relative; aspect-ratio: 975 / 977">
  <img src="/map.webp" alt="Gateway map" style="width: 100%; height: 100%">
  <svg viewBox="-505 -607 1112 1116" style="position: absolute; inset: 0; width: 100%; height: 100%">
    <path d="M217 -18A11 11 0 0 0 239 -18A11 11 0 0 0 217 -18Z" fill="rgb(52 211 153 / .25)" />
  </svg>
</div>

GET /v1/map/heat devolve onde a população do servidor anda: uma grade de 48 por 48, com um dígito de 0 a 8 por célula em levels[row * columns + column], a linha 0 em cima. Só contagem, sem nome nem ponto, e só no plano que tem o mapa de calor. Sem medição na última hora, vem "status": "cold".

{
  "status": "ok",
  "columns": 48,
  "rows": 48,
  "levels": "000000000001233210000…",
  "samples": 37,
  "measuredAt": "2026-10-07T22:39:00.000Z",
  "bounds": { "xMin": -505000, "xMax": 607000, "yMin": -607000, "yMax": 509000 }
}

// Node 18+, no dependencies. Run:
//   SPIRO_LAND_KEY=sl_sec_... STEAM_ID=76561198000000001 node spiro-map-own.mjs
// The key needs the Map permission. Your server keeps the image: the key never reaches the browser.
import { createServer } from "node:http";

const API = "https://spiro.land/api/v1";
const api = (path) => fetch(`${API}/${path}`, { headers: { Authorization: `Bearer ${process.env.SPIRO_LAND_KEY}` } });
const esc = (text) => text.replace(/[&<>"]/g, (c) => "&#" + c.charCodeAt(0) + ";");

// The map and the image, downloaded again only when the version changes.
let map = null;
let image = null;
async function refresh() {
  map = await (await api("map")).json();
  const color = map.layers.find((layer) => layer.id === "color");
  if (image?.version !== color.version) {
    image = { version: color.version, bytes: Buffer.from(await (await api("map/image?layer=color")).arrayBuffer()) };
  }
}
setInterval(refresh, 6 * 60 * 60 * 1000);

createServer(async (req, res) => {
  if (map === null) await refresh();
  if (req.url === "/map.webp") {
    return res.writeHead(200, { "Content-Type": "image/webp", "Cache-Control": "public, max-age=86400" }).end(image.bytes);
  }
  if (req.url === "/position") {
    // On your site, STEAM_ID is the player who signed in (verification or your own Steam login).
    const r = await api(`players/${process.env.STEAM_ID}/map`);
    return res.writeHead(r.status, { "Content-Type": "application/json" }).end(await r.text());
  }
  if (req.url !== "/") return res.writeHead(404).end();

  const sanctuaries = map.zones
    .filter((zone) => zone.kind === "sanctuary")
    .map((zone) => `<path d="${zone.path}"><title>${esc(zone.name)}</title></path>`)
    .join("");
  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(`<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Live map</title>
<div style="position:relative;max-width:900px;aspect-ratio:${map.image.width}/${map.image.height}">
  <img src="/map.webp" alt="Gateway map" style="display:block;width:100%;height:100%">
  <svg viewBox="${map.svg.viewBox}" style="position:absolute;inset:0;width:100%;height:100%"
    fill="rgb(52 211 153 / .25)" stroke="rgb(52 211 153)" stroke-width="1">${sanctuaries}</svg>
  <div id="me" hidden style="position:absolute;width:12px;height:12px;margin:-6px;border-radius:50%;background:#f43f5e;outline:2px solid #fff"></div>
</div>
<script>
  const b = ${JSON.stringify(map.bounds)};
  async function tick() {
    const body = await (await fetch("/position")).json();
    const me = document.getElementById("me");
    me.hidden = !body.player;
    if (!body.player) return;
    me.style.left = ((body.player.x - b.xMin) / (b.xMax - b.xMin)) * 100 + "%";
    me.style.top = ((body.player.y - b.yMin) / (b.yMax - b.yMin)) * 100 + "%";
  }
  tick();
  setInterval(tick, 5000);
</script>`);
}).listen(3000, () => console.log("Open http://localhost:3000"));

Baixar o exemplo pronto (spiro-map-own.mjs) Rode com a sua chave secreta e um SteamID, e abra http://localhost:3000: a imagem, os santuários e o jogador, relido a cada 5 segundos.

Segurança

• Só a chave secreta lê o mapa. Chame a API do servidor do seu site; o navegador recebe só a url do embutido, ou a imagem e as posições pelo seu servidor.
• Abra o embutido e leia a posição só do jogador que entrou no seu site: quem tem a url vê aquele jogador e o grupo dele.
• A página do mapa só abre dentro de um iframe, e só nos sites da chave. Aberta numa aba ela é 404, e o navegador recusa desenhá-la num site que não está na lista.
• Revogar a chave, tirar a permissão do mapa ou desligar o mapa ao vivo derruba os embutidos na leitura seguinte; desligado, a API responde 403 liveMapOff.
• A imagem sai só pela chave secreta com a permissão do mapa, com spiro.land gravado num canto. Sirva do seu servidor e não recorte a marca.

O jogador liga a Kick dele no seu site e passa a ganhar moedas na carteira do servidor assistindo e conversando na live do streamer parceiro, na própria Kick. O spiro.land conta, junta os centavos e credita; o seu site mostra os canais e a regra, e abre a ligação da conta. O jogador não precisa entrar no spiro.land.

Mostrar os canais e a regra

GET /v1/kick devolve os canais conectados, quem está ao vivo e o link de cada um, a regra e a moeda do servidor. Ele pede kick:read e funciona também com a chave pública: é o que a Kick e o painel do jogador já mostram.

{
  "status": "ready",
  "currency": { "singular": "coin", "plural": "coins" },
  "rule": {
    "coinsPerInterval": 10,
    "intervalMinutes": 10,
    "coinsPerMessage": 0.1,
    "messageCooldownSeconds": 30,
    "packages": [
      { "minutes": 10, "points": 20, "coins": 10 },
      { "minutes": 60, "points": 120, "coins": 60 }
    ]
  },
  "channels": [
    { "slug": "goldzeraa", "name": "Goldzeraa", "live": true, "url": "https://kick.com/goldzeraa" }
  ]
}

ready

Regra ligada e ao menos um canal: assistir e conversar pagam.

off

A regra está desligada ou não há canal conectado. Nada paga até a administração ligar.

unavailable

A Kick está fora do ar no spiro.land agora, ou o plano não a inclui.

O tempo assistido paga pelos pontos do canal: o espectador junta pontos assistindo logado na Kick e troca por um pacote no menu de recompensas do canal. Cada pacote em packages custa points e vale a parte de coinsPerInterval pelos minutos dele. Cada mensagem com a live no ar paga coinsPerMessage, uma por pessoa a cada messageCooldownSeconds. O que fica abaixo de uma moeda acumula e entra na carteira quando fecha uma.

Ligar a Kick do jogador

1. 01Dê a permissão e o endereço de volta

   Em Onde fica:Integrações›, API, numa chave secreta, marque kick:write e cadastre em Endereços de volta o endereço do seu site que recebe o jogador depois da Kick, como https://seusite.com/ligar/volta.

2. 02Abra a ligação no seu servidor

   Quando o jogador clicar para ligar a Kick, o servidor do seu site chama POST /v1/players/{steamId}/kick-link com o SteamID de quem entrou no seu site (pela verificação ou pelo seu login Steam), o redirectUri cadastrado e um state aleatório guardado na sessão dele. Mande o navegador para kickLink.url.

   JSONCopiar

   {
     "kickLink": {
       "id": "kl_Ab3xQ9mK2LwP7tRz",
       "status": "pending",
       "url": "https://spiro.land/api/v1/kick-links/kl_Ab3xQ9mK2LwP7tRz/start",
       "expiresAt": "2026-10-11T15:15:00.000Z"
     }
   }

3. 03O jogador autoriza na Kick e volta

   O spiro.land só redireciona: o jogador vê a tela de autorização da Kick e volta ao redirectUri com kickLink, state e code, ou com error. Compare o state com o da sessão antes de qualquer coisa.

   Copiar

   https://yoursite.com/kick/return
     ?kickLink=kl_Ab3xQ9mK2LwP7tRz
     &state=f3Kq9xLm2PwZ7tRb
     &code=Qm8xT2vLk9PzR4wN7cJ1yB5hD3sF6gA0eU8iO2pK4tY

4. 04Troque o código

   O servidor do seu site chama POST /v1/kick-links/{linkId}/exchange com o code. Só aí o vínculo grava: dali em diante, o que o jogador ganha na Kick cai na carteira dele. redemptionsCredited diz quantos resgates feitos antes do vínculo foram pagos agora.

   JSONCopiar

   {
     "kickLink": { "id": "kl_Ab3xQ9mK2LwP7tRz", "status": "linked", "linkedAt": "2026-10-11T15:01:12.000Z" },
     "player": { "steamId": "76561198000000001" },
     "account": { "name": "rex_on_kick" },
     "redemptionsCredited": 0
   }

Quando algo dá errado, a volta traz error no lugar de code:

cancelled

O jogador recusou na tela da Kick.

otherAccount

Esta conta da Kick já está ligada a outra Steam. O jogador desliga lá antes.

refused

A volta chegou de um navegador que não começou esta ligação. Nada mudou.

expired

A ligação venceu (15 minutos) ou já tinha acabado. Abra outra.

alreadyStarted

O endereço da ligação foi aberto mais de uma vez. Abra outra.

alreadyUsed

A volta da Kick já tinha chegado antes.

failed

A Kick não confirmou a conta. Tente de novo.

unavailable

A ligação de contas da Kick está fora do ar agora.

O que o jogador está juntando

GET /v1/players/{steamId}/kick-link, com players:read, diz se o jogador ligou a Kick, com o nome da conta, e accumulating: o que ele ganhou abaixo de uma moeda, que entra na carteira quando fecha uma. As moedas inteiras já estão na carteira.

{
  "linked": true,
  "account": { "name": "rex_on_kick", "linkedAt": "2026-10-11T15:01:12.000Z" },
  "accumulating": 0.7,
  "pendingRedemptions": 0
}

DELETE /v1/players/{steamId}/kick-link desfaz o vínculo e responde { "unlinked": true }. As mensagens e os resgates seguintes deixam de pagar a esta Steam.

// Node 18+ (fetch and crypto are built in). SPIRO_LAND_KEY: a secret key with kick:write and
// players:read, with RETURN in its return addresses.
import { randomBytes } from "node:crypto";

const API = "https://spiro.land/api/v1";
const RETURN = "https://yoursite.com/kick/return"; // registered on the key
const headers = {
  Authorization: `Bearer ${process.env.SPIRO_LAND_KEY}`,
  "Content-Type": "application/json",
};

// 1. The signed-in player clicked "Link Kick": redirect the browser to the url this returns.
//    steamId is the player your site already proved (verification or your own Steam login).
export async function startKickLink(session, steamId) {
  session.kickState = randomBytes(24).toString("base64url");
  const r = await fetch(`${API}/players/${steamId}/kick-link`, {
    method: "POST",
    headers,
    body: JSON.stringify({ redirectUri: RETURN, state: session.kickState }),
  });
  const body = await r.json();
  if (!r.ok) throw new Error(body.error.code);
  return body.kickLink.url;
}

// 2. The browser came back to RETURN. query: the parsed query string of that request.
export async function finishKickLink(session, query) {
  const expected = session.kickState;
  delete session.kickState;
  if (!expected || query.state !== expected) throw new Error("state mismatch");
  if (query.error) throw new Error(query.error); // cancelled, otherAccount, expired...

  const r = await fetch(`${API}/kick-links/${encodeURIComponent(query.kickLink)}/exchange`, {
    method: "POST",
    headers,
    body: JSON.stringify({ code: query.code }),
  });
  const body = await r.json();
  if (!r.ok) throw new Error(body.error.code);
  return body.account.name; // the Kick account now earning coins for this player
}

// 3. The Kick card on your site: the channels, the rule and what the player is collecting.
export async function kickCard(steamId) {
  const [kick, link] = await Promise.all([
    fetch(`${API}/kick`, { headers }).then((r) => r.json()),
    fetch(`${API}/players/${steamId}/kick-link`, { headers }).then((r) => r.json()),
  ]);
  return { kick, link };
}

Segurança

• Só a chave secreta liga e lê o vínculo. Chame a API do servidor do seu site; o navegador recebe só a url da ligação.
• Abra a ligação só para a Steam de quem entrou no seu site: é a Steam que você mandou que passa a receber o que aquela Kick ganhar.
• Compare o state antes de trocar: um link que vazou volta no navegador de outra pessoa, com o state da sessão dela, e não deve ser trocado.
• Uma conta da Kick paga uma Steam só. Ligada a outra, a troca responde 409 kickAccountInUse e nada muda.
• As moedas saem do spiro.land, pela regra do servidor. O seu site não credita nada pela Kick: ele só mostra e liga.

O jogador fala com quem está perto do dino dele, pela aba Voz do painel do jogador no spiro.land ou dentro do site do servidor. O áudio vai direto entre o navegador e o painel da VPS do servidor. Pela API, o seu site mostra se a voz está no ar, abre a voz para o jogador e modera.

• O estado da voz: ligada, no ar, a porta, quantos estão nela e o link para entrar.
• Se um jogador pode entrar e se ele está fora da voz.
• Tirar e devolver um jogador da voz.
• A voz dentro do seu site, num iframe: pronta no Dash, sem programar, ou aberta pelo seu servidor. O login do jogador é numa janela do spiro.land.

O que não existe, e não vai existir:

• Abrir a voz por um jogador, ouvir a voz ou falar por alguém.
• Saber quem fala, quem ouve quem, o volume ou onde cada um está.
• Saber se um jogador está na voz agora.

O estado e o link

GET /v1/voice com voice:read, que a chave pública também recebe. Responde sempre 200 com plano válido, e status diz o estado.

{
  "status": "ready",
  "enabled": true,
  "panel": { "ready": true, "online": true },
  "port": { "status": "ok", "transport": "udp", "checkedAt": "2026-10-13T18:40:00.000Z" },
  "inVoice": 12,
  "rangeMeters": 50,
  "joinUrl": "https://spiro.land/players?s=Ab3xQ9mK2LwP7tRzYc1VbQ&tab=voice",
  "asOf": "2026-10-13T18:41:02.000Z",
  "stale": false
}

ready

Ligada e no ar: o jogador entra pelo link.

off

A administração do servidor desligou a voz.

panelNotReady

O painel do servidor ainda não tem a voz: precisa ser atualizado.

panelOffline

O painel do servidor está fora do ar agora.

portFailed

Jogadores tentaram e ninguém conectou: a porta da voz está fechada no provedor.

untested

Ligada, e ninguém entrou ainda: a porta não foi testada.

port diz se a porta funciona e por qual transporte, e nunca traz IP nem número. joinUrl leva à aba Voz do painel do jogador e usa o id público do servidor, que muda quando o dono troca a chave do painel: leia daqui, não guarde.

Um botão que abre a voz

O jeito mais simples com a API: o seu site abre joinUrl numa aba nova. É a aba Voz do painel do jogador: o login e a voz rodam no spiro.land, o microfone fica com o spiro.land, e o seu site não muda cabeçalho nenhum.

<!-- A public key with voice:read, with your site in its origins. -->
<button id="voice" hidden>Join voice</button>
<script>
  const KEY = "sl_pub_...";
  fetch("https://spiro.land/api/v1/voice", { headers: { Authorization: `Bearer ${KEY}` } })
    .then((r) => r.json())
    .then((voice) => {
      if (voice.status !== "ready") return; // off, panelOffline...: keep the button hidden
      const button = document.getElementById("voice");
      button.textContent = `Join voice (${voice.inVoice} in voice now)`;
      button.hidden = false;
      // The Voice tab of the player panel: the player signs in there, never on your site.
      button.onclick = () => window.open(voice.joinUrl, "_blank", "noopener");
    });
</script>

Sem programar: o código do Dash

Em Onde fica:Jogadores›, Painel do jogador›, Voz de proximidade›, Voz no seu site, o dono escreve o endereço do site e copia um iframe pronto. Não precisa de chave, de servidor nem de código: o iframe não vence, só aparece nos endereços que ele escreveu, e continua valendo quando a VPS muda.

<iframe src="https://spiro.land/embed/voice?id=vs_Ab3xQ9mK2LwP7tRz" title="Proximity voice"
        allow="microphone; autoplay"
        style="width: 100%; max-width: 480px; height: 560px; border: 0"></iframe>

Pelo seu servidor, com a API

Num iframe, a voz fica na sua página. O jogador entra com a conta dele numa janela do spiro.land, que devolve ao iframe uma credencial só para documentos do spiro.land. Ela pula o login por até 30 dias; cada entrada na voz continua pedindo o clique do jogador e confere de novo o vínculo e o ban.

1. 01Abra o embutido pelo seu servidor

   Dê a permissão voice:embed a uma chave secreta, com o seu site na lista de sites, em Onde fica:Integrações›, API. Para cada visita, o seu servidor chama POST /v1/voice/embed, sem SteamID nenhum, e recebe o endereço do iframe.

   JSONCopiar

   {
     "embed": {
       "id": "emb_Ab3xQ9mK2LwP7tRz",
       "url": "https://spiro.land/embed/voice?id=emb_Ab3xQ9mK2LwP7tRz#Qm8xT2vLk9PzR4wN7cJ1yB5hD3sF6gA0eU8iO2pK4tY",
       "expiresAt": "2026-10-13T19:41:02.000Z"
     }
   }

2. 02Ponha o iframe na página

   Com allow="microphone; autoplay": sem ele, o navegador não deixa o iframe pedir o microfone.

   HTMLCopiar

   <iframe src="{embed.url}" title="Proximity voice"
           allow="microphone; autoplay"
           style="width: 100%; height: 420px; border: 0"></iframe>

3. 03Confira os cabeçalhos do seu site

   A sua página precisa deixar o spiro.land em frames e não pode usar COOP same-origin: com ele, a janela do login nasce sem caminho de volta ao iframe, e o iframe pede ao jogador que use a janela que abriu (vira o botão do passo anterior). Se você manda uma Permissions-Policy, inclua o spiro.land no microfone.

   Copiar

   Content-Security-Policy: frame-src https://spiro.land
   Cross-Origin-Opener-Policy: same-origin-allow-popups
   Permissions-Policy: microphone=(self "https://spiro.land")

Um jogador

GET /v1/players/{steamId}/voice, com players:read (só chave secreta), diz se aquele jogador pode entrar e por que não. Nunca diz se ele está na voz.

ready

Pode entrar pelo link.

off

A voz está desligada no servidor.

banned

Está fora da voz: o voiceBan diz até quando e por quê.

noProof

O vínculo dele não foi provado pela Steam: ele vincula a conta no spiro.land antes de entrar.

panelNotReady

O painel do servidor ainda não tem a voz.

panelOffline

O painel do servidor está fora do ar agora.

Moderar

POST /v1/players/{steamId}/voice-ban com voice:write tira o jogador da voz, com motivo de 1 a 200 caracteres e durationMinutes de 1 a 525600 minutos, ou null para sem prazo. Funciona com a voz desligada, para moderar antes de ligar.

{
  "voiceBan": {
    "steamId": "76561198000000002",
    "until": "2026-10-14T18:00:00.000Z",
    "reason": "Ofensas na voz",
    "createdBy": "api:key_8fK2mQ1xZp0a",
    "createdAt": "2026-10-13T18:00:00.000Z"
  },
  "disconnect": "requested"
}

disconnect diz se havia uma sessão para derrubar. DELETE /v1/players/{steamId}/voice-ban devolve a voz. GET /v1/voice/bans com bans:read lista quem está fora. O Dash mostra os mesmos, com a autoria da chave.

Privacidade

• A Spiro não grava nem transcreve a voz, e o áudio não passa pela Spiro: vai do navegador ao painel da VPS do servidor.
• Nenhuma resposta traz posição, quem fala, quem ouve quem ou volume. A contagem de quem está na voz é agregada.
• Com a voz desligada, abrir o embutido responde 403 voiceOff, e quem estava na voz sai.
• Um jogador tem uma sessão de voz só: abrir em outro lugar derruba a anterior, e o jogo avisa na tela quando a voz liga.

Todo erro tem a mesma forma. code é o contrato e não muda; message é para você ler, em inglês, e pode mudar.

{
  "error": {
    "code": "scopeMissing",
    "message": "This key does not have the permission this endpoint needs.",
    "scope": "killfeed:read"
  }
}

Toda resposta leva X-Request-Id. Cite esse id se falar com o suporte.

A API não responde 5xx num estado esperado: painel fora do ar, dado que ainda não chegou e API desligada voltam como 4xx, como 409 panelOffline, e quem decide o que fazer é o code, nunca só o número. Um 5xx é defeito nosso (500 internal), e a hospedagem pode trocá-lo por uma página HTML com HTTP 200. Trate resposta que não é JSON como esse defeito: numa escrita, repita com a mesma Idempotency-Key, que o jogo faz uma vez só.

Cada chave tem as permissões que o dono marcou, e um endpoint sem a permissão dele responde 403 scopeMissing. As que agem mexem no jogo e só existem na chave secreta.

Todos os endpoints da v1, pelo assunto. Os que leem campos do pedido trazem a lista e um exemplo pronto para colar.