Documentation

Authentication

Sign one message for a 30-day session token, or sign each request, depending on the route.

Public reads need nothing. Routes that change your own account prove it in one of two ways: ordinary settings take a 30-day session bearer, minted by signing one off-chain message; a display name or a bio carries its own wallet signature on every request. No route here can move money.

The split is about what the change claims. Following someone, linking a Telegram chat, putting an email on file and saying something in the channel are your own account, and a session bearer is enough for them. A display name or a bio is a public claim on an identity, which is why each of those requests is signed on its own.

A session token

  1. Ask for the server's clock GET /auth/start returns { issued }, a Unix timestamp in seconds. Stamping the server's time rather than the device's keeps a skewed clock from falling outside the window.
  2. Sign the message An off-chain SEP-0053 signature over the exact string below, with the network passphrase of this deployment. It is not a transaction, costs nothing, and moves nothing.
  3. Exchange it POST /auth with { address, issued, signature } returns { token, address, exp }.
win-trader: sign in
address: <G...>
issued: <seconds>
network: <passphrase>
Authorization: Bearer <token>

The token lasts 30 days: sign in once, reuse everywhere. The signature itself is accepted for five minutes after issued, which is the replay window rather than the session.

Routes that take a session bearer

MethodPathAnswers
GET/auth/startThe server's clock. Needs nothing.
POST/authSignature in, session token out.
GET/chatThe last 50 lines of the channel. A bearer is optional and only marks your own lines.
POST/chatSay something, up to 280 characters, at most once every 750ms. (authenticated)
POST/followFollow a trader. (authenticated)
DELETE/followStop following one. (authenticated)
POST/emailPut an email on file. (authenticated)
POST/telegram/link/startMint the code that connects a Telegram chat. (authenticated)
GET/telegramYour alert link's state. (authenticated)
POST/telegram/visibilityShow or hide the link on your profile. (authenticated)
DELETE/telegramUnlink it. (authenticated)
POST/crowns/visibilityShow or hide your crowns next to your name. (authenticated)

Routes that take a wallet signature

Each of these carries the address, a timestamp and a SEP-0053 signature over a message that names the change. The signature is accepted for three minutes. See Your name and profile for what a name costs.

MethodPathAnswers
GET/name/priceWhat ?address= would pay for its next change: free changes left, paid credits, the price in stroops, the fee address and the memo. Public.
POST/name/paymentCredit a settled XLM payment, by transaction hash, as one paid change.
POST/nameClaim a display name. 402 when a payment is due, 409 when the name is taken.
POST/bioSet your bio. Needs a name first.

There is no route on this host that can move money, and that is not an oversight. Depositing, withdrawing, opening and closing are transactions your wallet signs and the chain settles; see How settlement works.