Anonymous Access

You can call signal endpoints without an API key. Anonymous callers get basic metadata only and a quota of 5 signal requests per calendar month per IP. Beyond that, requests return 429.

The basic-tier response includes:

signal_id, signal_type, timestamp, signal_expiry
Full market info (platform, market_id, question, category, volume, etc.)
signal.direction, signal.price_before, signal.price_after
analysis.wallet_historical_win_rate, analysis.decay_applied

Premium fields (flow_type, total_flow_usd, time_window_sec, average_entry_price, consensus_wallet_count, expected_value, narrative, x_pulse_score) are returned as null.

GET /v1/signals/{signal_id}/entities (wallet-level detail) requires an API key — anonymous calls return 401.

Get a Free API Key (Beta)

Sona is in open beta. Sign up at /docs/quick-start and you'll receive a key prefixed sk_beta_… instantly. During beta this key:

Removes the 5/month quota (unlimited signal requests)
Returns the full payload (all premium fields populated)
Unlocks /v1/signals/{signal_id}/entities

The first 100 signups also lock in the Founding rate (50% off Pro for 12 months) when paid plans launch. Live counter is on /docs/quick-start.

Sending Your Key

Pass the key as a Bearer token on every request:

curl "https://api.agentsona.com/v1/signals/latest?limit=5" \
  -H "Authorization: Bearer sk_beta_YOUR_KEY"

fetch('https://api.agentsona.com/v1/signals/latest?limit=5', {
  headers: { Authorization: 'Bearer sk_beta_YOUR_KEY' },
})

Tiers & Pricing

Tier	Access	Price
Anonymous	5 signals/month, basic metadata	Free
Beta member	Unlimited, full context	Free during beta
Pro	Unlimited, full context	$99/mo
Pro Founding	Unlimited, full context	$49.50/mo for 12 months (first 100 only)
Agent	Custom	Contact us

Beta usage runs on fair-use; per-minute caps are not enforced for sign-ups during beta. Paid plans will reintroduce per-tier limits at launch.

Error Codes

Code	Meaning
`400`	Invalid request payload or parameters
`401`	Endpoint requires an API key (e.g. `/entities`)
`403`	Request not allowed for the current key
`404`	Requested resource not found
`409`	Email already registered (signup endpoint)
`422`	Invalid typed request body or query params
`429`	Rate limit or anonymous monthly quota exceeded
`500`	Internal server error
`503`	Service temporarily unavailable

All error responses follow this shape:

{
  "detail": "description of the error"
}

For on-demand signal endpoints, a missing market or a request that produces no qualifying signal returns 200 with an empty data array rather than 404.

Base URL

https://api.agentsona.com/v1

Key Hygiene

Treat your sk_beta_ key like a password. Don't commit it; don't paste it in tickets or chat.
The full key is shown once on signup and emailed to you. Regenerate by contacting contact@agentsona.com.
Keys are non-transferable. Sharing forfeits Founding status.

Authentication