Docs

API reference

Auth

Wallet sign-in with an EIP-191 personal_sign message, and the bearer token it returns.

Reading data never needs auth. Sign-in is only for annotations, proposals, votes and webhooks.

Flow#

  1. POST /v1/auth/nonce with your address. You get a message to sign.
  2. Sign the message with personal_sign (EIP-191). No transaction, no gas.
  3. POST /v1/auth/verify with the address and signature. You get a token.
  4. Send Authorization: Bearer <token> on signed-in requests.

POST /v1/auth/nonce#

Request·json
{ "address": "0x…" }
Response shape·json
{ "message": "string (sign this exactly)" }

POST /v1/auth/verify#

Request·json
{ "address": "0x…", "signature": "0x…" }
Response shape·json
{ "token": "string", "wallet": "address" }

GET /v1/me#

Returns the signed-in wallet. Use it to check a token is still valid.

Example (browser, viem)#

sign-in.ts·ts
import { createWalletClient, custom } from "viem";
import { base } from "viem/chains";

const API = "https://dapp.forgeus.science";
const wallet = createWalletClient({ chain: base, transport: custom(window.ethereum!) });
const [address] = await wallet.requestAddresses();

const post = (path: string, body: unknown) =>
  fetch(API + path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }).then((r) => r.json());

const { message } = await post("/v1/auth/nonce", { address });
const signature = await wallet.signMessage({ account: address, message });
const { token } = await post("/v1/auth/verify", { address, signature });

const me = await fetch(API + "/v1/me", { headers: { authorization: `Bearer ${token}` } }).then((r) => r.json());

Any library that does personal_sign works the same way.

Paper only. No funds are traded. $FOUS is not launched. Nothing here is financial advice.