API Reference | SellSignal

// authentication

Issue a key from Settings → API. The raw key is shown exactly once; copy it before closing the dialog. You can have up to 5 active keys per account; revoking a key takes effect immediately.

Authorization: Bearer ss_live_<your-key>

Free-tier accounts can issue keys but cannot call the API — upgrade to Pro at /pricing.

// rate limits

100 requests / minute per key, sliding window. Exceeding the limit returns 429 RATE_LIMITED withRetry-After, , and headers.

// envelopes

Successful responses return:

{ "data": <payload>, "meta": { ... } }

Errors return:

{ "error": { "code": "STRING", "message": "human-readable" } }

Common error codes:

UNAUTHORIZED · 401 — missing or malformed bearer
INVALID_KEY · 401 — key not found or revoked
FORBIDDEN · 403 — non-Pro tier
NOT_FOUND · 404 — resource doesn't exist or isn't yours
VALIDATION_ERROR · 400 — bad request body
RATE_LIMITED · 429 — over the per-key limit
STABLECOIN · 400 — analysis attempted on a pegged asset
DB_ERROR · 500 — backend persistence failure

// endpoints

POST/api/v1/analysis

Run a new analysis. Supported types: exit_plan, health_check, market_brief. Returns 201 with the persisted analysis (also retrievable via the GET-by-id route).

curl -X POST https://www.sellsignal.app/api/v1/analysis \
  -H "Authorization: Bearer $SS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "exit_plan",
    "symbol": "BTC",
    "position": { "entryPrice": 62000, "quantity": 1.0 },
    "riskProfile": "moderate"
  }'

GET/api/v1/analysis/:id

Fetch a previously stored analysis. Scoped to your own analyses.

GET/api/v1/positions

List your positions ordered newest-first.

POST/api/v1/positions

Create a position.

curl -X POST https://www.sellsignal.app/api/v1/positions \
  -H "Authorization: Bearer $SS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "symbol": "ETH", "entry_price": 3200, "quantity": 2.5 }'

// quickstart (javascript)

const SS_KEY = process.env.SS_KEY;

const res = await fetch("https://www.sellsignal.app/api/v1/portfolio", {
  headers: { Authorization: `Bearer ${SS_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const { data } = await res.json();
console.log(data.summary);

// quickstart (python)

import os, requests

SS_KEY = os.environ["SS_KEY"]

r = requests.get(
    "https://www.sellsignal.app/api/v1/portfolio",
    headers={"Authorization": f"Bearer {SS_KEY}"},
)
r.raise_for_status()
print(r.json()["data"]["summary"])

// not in v1

Webhooks (will be its own version)
OpenAPI spec / SDK generation
Per-key scopes (read-only vs read-write)
Analysis types beyond exit_plan / health_check / market_brief — ask if you need comparison or scenario over the API.