Authentication

The gateway authenticates requests with API keys. You get a key by proving control of a Stellar wallet: request a challenge, sign it with the wallet, and exchange the signed proof for a keyId + secret pair. This page covers the full flow, the exact request and response shapes, and key management.

Base URL for all examples: https://noetherapi-production.up.railway.app (Stellar testnet deployment).

What a key looks like

The secret is shown once, in the issuance response. The gateway stores only a peppered SHA-256 hash of it — there is no way to retrieve a lost secret. Revoke the key and mint a new one instead.

Check beta status

Public, no auth required. Pass your address to see whether you can mint a key:

curl -s "https://noetherapi-production.up.railway.app/v1/keys/beta-status?address=GBTRADER..."

{ "gated": true, "allowed": false }

• gated — whether an allowlist is configured at all.
• allowed — true when issuance is open to everyone, or when the supplied address is on the list. Without an address parameter, allowed is false whenever the gate is on.

Getting a key

curl -s -X POST https://noetherapi-production.up.railway.app/v1/keys/challenge \
  -H "content-type: application/json" \
  -d '{"address":"GBTRADER..."}'

{ "challengeHex": "9f8e...64-hex-chars...", "expiresAt": 1720000300000 }

// sign-challenge.ts — build and sign the placeholder transaction
import {
  Account, Keypair, Operation, TransactionBuilder,
} from '@stellar/stellar-sdk';
 
const NETWORK_PASSPHRASE = 'Test SDF Network ; September 2015';
 
function signChallenge(challengeHex: string, keypair: Keypair): string {
  const placeholder = Keypair.random().publicKey(); // dummy source account
  const account = new Account(placeholder, '0');    // sequence 0
  const tx = new TransactionBuilder(account, {
    fee: '0',
    networkPassphrase: NETWORK_PASSPHRASE,
  })
    .addOperation(Operation.manageData({
      name: 'noether-api auth',
      value: Buffer.from(challengeHex, 'hex'),      // the 32 challenge bytes
      source: keypair.publicKey(),                  // your address
    }))
    .setTimeout(0)
    .build();
  tx.sign(keypair);
  return tx.toXDR(); // base64 signed-transaction XDR
}

curl -s -X POST https://noetherapi-production.up.railway.app/v1/keys \
  -H "content-type: application/json" \
  -d '{
    "address": "GBTRADER...",
    "challenge": "9f8e...the challengeHex...",
    "signature": "AAAAAgAAA...base64-signed-tx-XDR...",
    "label": "trading-bot"
  }'

{
  "keyId": "nk_3f9a1c0b8d2e4f6a7b8c9d0e",
  "secret": "64-hex-char-secret...",
  "tier": "standard",
  "owner": "GBTRADER...",
  "createdAt": 1720000000000
}

curl -s https://noetherapi-production.up.railway.app/v1/account/me \
  -H "Authorization: Bearer nk_3f9a1c0b8d2e4f6a7b8c9d0e:64-hex-char-secret..." \
  -H "X-Timestamp: $(date +%s)"

{ "owner": "GBTRADER...", "tier": "standard", "keyId": "nk_3f9a1c0b8d2e4f6a7b8c9d0e" }

The X-Timestamp header

X-Timestamp is optional replay protection. If you send it, the value must be the current unix time in seconds, within plus or minus 30 seconds of server time — otherwise the request fails with 401 stale_timestamp. If you omit it, no timestamp check happens (HTTPS is the primary transport protection). The official SDKs send it by default on authenticated calls.

Authentication errors

All auth failures are 401 with a small JSON body:

Managing keys

List your keys

GET /v1/keys (requires auth) returns every key with the same owner as the authenticated key, newest first, including revoked ones:

curl -s https://noetherapi-production.up.railway.app/v1/keys \
  -H "Authorization: Bearer nk_3f9a1c0b8d2e4f6a7b8c9d0e:64-hex-char-secret..."

{
  "keys": [
    {
      "keyId": "nk_3f9a1c0b8d2e4f6a7b8c9d0e",
      "owner": "GBTRADER...",
      "tier": "standard",
      "label": "trading-bot",
      "createdAt": 1720000000000,
      "lastUsedAt": 1720000500000,
      "revokedAt": null
    }
  ]
}

Timestamps are millisecond epochs; label, lastUsedAt, and revokedAt may be null. lastUsedAt updates on every successful authentication. Secrets are never included.

Revoke a key

DELETE /v1/keys/{keyId} (requires auth). Any of your keys can revoke any key belonging to the same owner — including itself:

curl -s -X DELETE https://noetherapi-production.up.railway.app/v1/keys/nk_3f9a1c0b8d2e4f6a7b8c9d0e \
  -H "Authorization: Bearer nk_othervalidkey000000000000:64-hex-char-secret..."

{ "revoked": true }

Revocation takes effect immediately — the revoked key fails auth on its next request. If the key does not exist, belongs to a different owner, or is already revoked, you get 404 with {"error":"key_not_found"}.

No-code alternative: mint a key in the app

If you’d rather not script the challenge flow, the web app does it for you: connect your wallet at https://noether.exchange/api-keys, approve the signing prompt (it is the same never-submitted placeholder transaction), and copy the key pair from the screen. The same closed-beta gating applies.

Complete copy-paste flow

End to end with curl plus a small Node script for the signing step:

BASE=https://noetherapi-production.up.railway.app
ADDRESS=GBTRADER...   # your Stellar public key
 
# 1. Check the beta gate
curl -s "$BASE/v1/keys/beta-status?address=$ADDRESS"
 
# 2. Request a challenge (valid 5 minutes, single use)
CHALLENGE=$(curl -s -X POST "$BASE/v1/keys/challenge" \
  -H "content-type: application/json" \
  -d "{\"address\":\"$ADDRESS\"}" | node -pe 'JSON.parse(require("fs").readFileSync(0)).challengeHex')
 
# 3. Sign it (a script wrapping the signChallenge function above with your keypair)
SIGNED_XDR=$(npx tsx sign-challenge.ts "$CHALLENGE")
 
# 4. Exchange for a key — the secret in this response is shown ONCE
curl -s -X POST "$BASE/v1/keys" \
  -H "content-type: application/json" \
  -d "{\"address\":\"$ADDRESS\",\"challenge\":\"$CHALLENGE\",\"signature\":\"$SIGNED_XDR\",\"label\":\"my-bot\"}"
 
# 5. Use it (substitute the keyId and secret from step 4)
curl -s "$BASE/v1/account/me" \
  -H "Authorization: Bearer nk_yourkeyid:yoursecret" \
  -H "X-Timestamp: $(date +%s)"

Endpoint summary

Next steps

• REST API reference — every endpoint, including the prepare → sign → submit trading flow
• WebSocket — the login op uses this same key pair for private channels
• TypeScript SDK and Python SDK — handle the challenge flow and send X-Timestamp for you
• API explorer — try endpoints interactively
• Errors — the full error taxonomy