# Events on Algorand — Agent Guide (full)

See the short index: https://staging.eventsonalgorand.com/llms.txt

## Deployment environment

| Field | Value |
|-------|-------|
| EOA environment | `staging` |
| Algorand network | `testnet` |
| Mainnet production | no |
| Real ALGO / live contracts | no |

Staging deployment on Algorand testnet — sandbox only; not mainnet production.


**Warning:** Do not treat this host as mainnet production. Deployed app ids, treasury deposits, and on-chain state are on Algorand testnet.


Match your client dApp, explorer links, and funding wallet to this network before
deploying contracts.

Event state is published as-is. It is not an oracle for settlement, pricing, or
liquidations, and it carries no warranty of accuracy or uptime.

## Platform summary

Events on Algorand (EOA) tracks authoritative real-world event data and publishes
outcomes to shared Algorand smart contracts (`RWEContract`). Other dApps can:

- **Pull** — subscribe and read on-chain globals (`outcome`, `is_final`, etc.).
This deployment does not call other contracts.


Billing uses an in-platform microALGO ledger. Fund your account via the deposit
address returned by `GET /api/v1/me/`.

## Authentication (human-in-the-loop)


1. Human registers at https://staging.eventsonalgorand.com/accounts/signup/ and verifies email.

2. Human signs in at https://staging.eventsonalgorand.com/accounts/login/.
3. Human issues a Knox API token at https://staging.eventsonalgorand.com/dashboard/settings/api-token/ (one active token per user;
   re-issue revokes the previous token).
4. Agent uses `Authorization: Token <token>` on authenticated `/api/v1/` routes.

Unauthenticated public routes today: OpenAPI schema/UI and this discovery bundle.

## OpenAPI

Primary contract for agents:

- Schema JSON: https://staging.eventsonalgorand.com/api/v1/schema/
- Accept header: `application/vnd.oai.openapi+json`
- Human UI: https://staging.eventsonalgorand.com/api/v1/schema/ui/

Read the schema before calling endpoints. Field descriptions, enums, and response
shapes are authoritative.

## Event sources

| Source | `source` value | `external_id` |
|--------|----------------|----------------|
| Kalshi | `kalshi` | Market ticker, e.g. `KXBTC-25DEC31` |
| NOAA Weather | `noaa` | `{STATION_ID}:{LOCAL_DATE}` e.g. `USW00094728:2026-09-12` |
| Polymarket | `polymarket` | Condition id or market URL/slug |


`GET /api/v1/sources/` returns `outcome_schema`, input hints, and trigger metadata
per source.

### Register an event

```
POST /api/v1/events/
Content-Type: application/json
Authorization: Token <token>

{"source": "kalshi", "external_id": "KXBTC-25DEC31"}
```

A `409` with code `kalshi_ambiguous` means the input matched multiple Kalshi markets. Follow `picker_path` and retry with a specific child id.

NOAA Weather notes:

- US GHCN stations only; inactive stations are rejected.
- Daily values use the station&#x27;s local calendar day, not UTC.
- Outcomes can be `VOID` if the provider never publishes within the resolution window. Smart contracts must handle VOID explicitly (see that source&#x27;s `outcome_schema`).
A `409` with code `polymarket_ambiguous` means the input matched multiple Polymarket markets. Follow `picker_path` and retry with a specific child id.


## Deploy a contract

```
POST /api/v1/contracts/
{"event_instance_id": 1234}
```

Deploy is asynchronous (`DEPLOYING` → poll `GET /api/v1/contracts/{id}/`). Fees are
reserved from your account balance.

## Subscribe (pull mode)

First subscriber deploys the contract; later subscribers join the existing one.

```
POST /api/v1/subscriptions/
{"event_instance_id": 1234}
```



## Account and billing

```
GET /api/v1/me/
GET /api/v1/account/
```

Returns balance, deposit address, and deposit memo. Top up before deploys.

## Rate limits

API read/write/subscribe endpoints are throttled per token/IP (see OpenAPI and
response headers). Prefer caching catalog data; do not scrape HTML search forms.

## Errors

Validation failures should return JSON problem details. Read `detail`, field keys,
and machine-readable `code` values to self-correct. A `409` includes `picker_path` when the input matched multiple markets.

## Pages agents should not rely on

- https://staging.eventsonalgorand.com/ — marketing; use API catalog instead.
- `/dashboard/*` — session UI with CSRF forms.
- `/accounts/*` — human auth flows.

## Related docs

- https://staging.eventsonalgorand.com/how-it-works/
- https://staging.eventsonalgorand.com/contract-lifecycle/
- https://staging.eventsonalgorand.com/terms/
- https://staging.eventsonalgorand.com/privacy/

## Discovery files

- Short index: https://staging.eventsonalgorand.com/llms.txt
- robots.txt: https://staging.eventsonalgorand.com/robots.txt
- sitemap.xml: https://staging.eventsonalgorand.com/sitemap.xml
- /.well-known/agent.json: https://staging.eventsonalgorand.com/.well-known/agent.json


## Contact

support@eventsonalgorand.com