# STATE Documentation — Full Text
# https://docs.instate.cc
# Last updated: 2026-04-08
# For machine consumption. See /llms.txt for a summary index.

---

# What is STATE?

STATE is an event-driven prediction market protocol on Solana that converts real-world outcomes into on-chain asset lifecycle transitions.

The ARK2 pipeline continuously ingests news from hundreds of RSS sources, canonicalizes signals, scores them by capital potential, generates prediction market metadata (titles, tickers, resolution criteria, bios), and catalogs them as READY events. AI agents or users can then launch these events as SPL tokens on a Solana bonding curve. When the real-world event resolves, the market resolves.

Key concepts:
- **Events**: Real-world outcomes tracked as prediction markets (e.g. "Greece to Ban Social Media for Under-15s")
- **Tickers**: Short symbol for each market (e.g. GRBAN, DEAL, USGOVWIN)
- **Bonding curve**: Capital-formation curve — price rises as more tokens are bought
- **ARK2**: The AI pipeline that processes news → prediction markets
- **Catalog**: Queue of READY events available to launch
- **Mint address**: Solana SPL token address, set when market is LAUNCHED

---

# Quick Start

Base URL: https://api.instate.cc

No authentication needed for read endpoints. Start with:

```bash
# See what markets are available right now
curl https://api.instate.cc/api/ready-events?limit=5

# Stream live events (SSE)
curl -N https://api.instate.cc/api/stream
```

---

# Authentication

## Option A: STATE Wallet (easiest for AI agents)

### Step 1: Create a wallet
```
POST https://api.instate.cc/api/wallet/create
Content-Type: application/json
{}
```

Response:
```json
{
  "success": true,
  "data": {
    "publicKey":  "Dhoe8M4tPk2WKuzavoy1aCjyZf6MWDgBSaxhsGD8H9zX",
    "privateKey": "h3teuZUPekgqoFyVNEsh14ChPniFzV6A2HCaaV9qUf8EWaFhihxvgQDYcjXfXkNF3A69umT4MSgpJKs74Xt1G3R",
    "walletType": "state"
  }
}
```

WARNING: Store your privateKey securely — it will never be shown again.

### Step 2: Get a nonce
```
GET https://api.instate.cc/api/auth/nonce?publicKey=YOUR_PUBLIC_KEY
```

Response:
```json
{ "nonce": "abc123xyz" }
```

### Step 3: Sign the message
Construct the message:
```
instate.cc agent authentication
YOUR_PUBLIC_KEY
<nonce>
<ISO timestamp>
```

Sign with your private key using Ed25519 (base58-encode the signature).

### Step 4: Verify and get JWT
```
POST https://api.instate.cc/api/auth/verify
Content-Type: application/json
{
  "publicKey": "YOUR_STATE_PUBLIC_KEY",
  "signature": "BASE58_ENCODED_SIGNATURE",
  "message":   "instate.cc agent authentication\nYOUR_PUBLIC_KEY\n<nonce>\n<timestamp>"
}
```

Response:
```json
{
  "success": true,
  "data": {
    "token":     "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "type":      "access",
    "expiresIn": 604800,
    "isNew":     false
  }
}
```

Use `Authorization: Bearer <token>` on all authenticated requests. Token valid 7 days.

---

## Option B: Solana Wallet

### Step 1: Generate keypair (Node.js)
```javascript
const { Keypair } = require('@solana/web3.js');
const bs58 = require('bs58');

const keypair = Keypair.generate();
console.log('Public key:', keypair.publicKey.toBase58());
console.log('Secret key:', bs58.encode(keypair.secretKey));
```

### Step 2: Get nonce
```
GET https://api.instate.cc/api/auth/nonce?publicKey=YOUR_SOLANA_PUBLIC_KEY
```

### Step 3: Sign SIWS challenge and verify
```
POST https://api.instate.cc/api/auth/solana/verify
Content-Type: application/json
{
  "publicKey": "YOUR_SOLANA_PUBLIC_KEY",
  "signature": "BASE58_ENCODED_SIGNATURE",
  "message":   "<SIWS message from nonce response>"
}
```

Auto-registered on first login. Returns same JWT structure as STATE wallet auth.

---

# SSE Event Stream

Connect to the real-time stream to receive prediction markets as they're cataloged and launched.

```bash
curl -N https://api.instate.cc/api/stream
```

On connect:
1. Replays last 200 catalog events (READY + LAUNCHED), oldest first
2. Emits `stream_ready` event
3. Pushes live events as they happen

Event types:

**catalog** — new READY market (use these to find launch targets):
```
id: cmnplty0g00rx6buctbsb128k
event: catalog
data: {
  "title": "India to Import 12.51 Million Barrels from Venezuela",
  "ticker": "DEAL",
  "question": "India to Import 12.51 Million Barrels from Venezuela",
  "description": "India is expected to import the highest volumes...",
  "proposedResolveBy": "2026-05-29T09:30:00.000Z",
  "proposedResolveWindowDays": 52,
  "evidenceUrls": ["https://oilprice.com/..."],
  "thumbnailUrl": "https://d32r1sh890xpii.cloudfront.net/...",
  "launchStatus": "READY",
  "mintAddress": null
}
```

**launched** — market went live on bonding curve:
```
event: launched
data: {
  "eventId": "cmnpw1y4302evmo4yo6zchqca",
  "mintAddress": "3L44TujKqP7Crzh2rJGn91yStoEm7js3npXBjcALusyr",
  "launchedAt": "2026-04-08T10:11:55.192Z",
  "launchStatus": "LAUNCHED"
}
```

**stream_ready** — replay complete:
```
event: stream_ready
data: {"replayComplete": true, "timestamp": "2026-04-08T10:00:00.000Z"}
```

---

# Launch Flow (6 steps, ~19 seconds end-to-end)

This is how a new token is created on STATE. An agent authenticates, picks an event, pays a 0.02 SOL fee, and the STATE backend creates the SPL token, sets up the bonding curve, and makes it tradeable.

## Step 1 — Authenticate
Get a JWT as described above.

## Step 2 — Discover events
```
GET https://api.instate.cc/api/ready-events?limit=10
Authorization: Bearer <jwt>
```

Events are sorted by score (capital reach × confidence). Top of list = best launch target.

Example response (abbreviated):
```json
{
  "events": [
    {
      "id": "cmnpw1y4302evmo4yo6zchqca",
      "title": "China to Approve Solid-State Battery Expansion",
      "ticker": "BEIJIWIN",
      "score": 0.89,
      "capitalReach": "$727K",
      "launchStatus": "READY"
    }
  ]
}
```

Also available: GET /api/ready-events?category=CRYPTO|FINANCE|POLITICS|DEFENCE|WORLD

## Step 3 — Get quote
```
POST https://api.instate.cc/api/agent/launch/quote
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "eventId": "cmnpw1y4302evmo4yo6zchqca"
}
```

Response:
```json
{
  "feeAmount": 0.02,
  "feeRecipient": "8uW5z1YA6c5AadQKCksr1yEFg7dKm9yMktNdCJduMyAe",
  "currency": "SOL"
}
```

## Step 4 — Pay launch fee
Send exactly 0.02 SOL to the feeRecipient address on Solana mainnet. Capture the transaction signature.

```javascript
const tx = new Transaction().add(
  SystemProgram.transfer({
    fromPubkey: wallet.publicKey,
    toPubkey: new PublicKey("8uW5z1YA6c5AadQKCksr1yEFg7dKm9yMktNdCJduMyAe"),
    lamports: 0.02 * LAMPORTS_PER_SOL,
  })
);
const sig = await sendAndConfirmTransaction(connection, tx, [wallet]);
```

## Step 5 — Submit launch
```
POST https://api.instate.cc/api/agent/launch
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "eventId":      "cmnpw1y4302evmo4yo6zchqca",
  "feeSignature": "YOUR_FEE_TX_SIGNATURE"
}
```

Response:
```json
{
  "success": true,
  "launchId": "cmnpw1y4302evmo4yo6zchqca",
  "message": "Launch queued — the backend will create the token and bonding curve"
}
```

## Step 6 — Poll for completion
```
GET https://api.instate.cc/api/agent/launch/cmnpw1y4302evmo4yo6zchqca
Authorization: Bearer <jwt>
```

Poll every 2 seconds. When `launchStatus === "LAUNCHED"`, the `mintAddress` field contains the Solana SPL token address.

```json
{
  "launchId": "cmnpw1y4302evmo4yo6zchqca",
  "launchStatus": "LAUNCHED",
  "mintAddress": "3L44TujKqP7Crzh2rJGn91yStoEm7js3npXBjcALusyr",
  "launchedAt": "2026-04-08T10:11:55.192Z",
  "title": "China to Approve Solid-State Battery Expansion",
  "ticker": "BEIJIWIN"
}
```

The BEIJIWIN token launched in 19 seconds. $727K capital reach. Fully on-chain.

---

# Trading (Buy / Sell)

## Buy tokens
```
POST https://api.instate.cc/api/curve/buy
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "mint":   "3L44TujKqP7Crzh2rJGn91yStoEm7js3npXBjcALusyr",
  "amount": 0.1
}
```

## Sell tokens
```
POST https://api.instate.cc/api/curve/sell
Authorization: Bearer <jwt>
Content-Type: application/json
{
  "mint":   "3L44TujKqP7Crzh2rJGn91yStoEm7js3npXBjcALusyr",
  "amount": 1000
}
```

---

# Developer Tools

## STATE Cursor Plugin
All-in-one plugin for Cursor IDE with subagents, skills, rules, and MCP servers for STATE development.
URL: https://docs.instate.cc/developer-tools/cursor-plugin

## MCP Server
Give AI agents direct access to STATE market operations and bonding curve data via the Model Context Protocol.
URL: https://docs.instate.cc/developer-tools/connect-sdk-mcp

## Bonding Curve Mechanics
Understand the capital-formation curve and how token prices are derived on-chain.
URL: https://docs.instate.cc/developer-tools/bonding-curve

## Market Resolution
How prediction markets resolve and how to integrate resolution events into your application.
URL: https://docs.instate.cc/developer-tools/market-resolution

## Debug Endpoints
Internal REST endpoints to trigger price broadcasts and inspect ARK2 pipeline state.
URL: https://docs.instate.cc/developer-tools/debug-endpoints

---

# Best Practices

1. Always validate transactions client-side before sending to STATE backend.
2. Use the SSE stream (/api/stream) instead of polling REST for real-time market discovery.
3. Handle bonding curve slippage — prices change between quote and execution.
4. Store no API secrets in frontend code; proxy through your backend.
5. JWT tokens expire after 7 days — refresh before expiry.
6. The top-ranked event in /api/ready-events is the highest-signal launch target at any moment.

---

# API Reference Summary

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | /api/wallet/create | None | Create STATE wallet |
| GET | /api/auth/nonce | None | Get signing nonce |
| POST | /api/auth/verify | None | STATE wallet sign-in → JWT |
| POST | /api/auth/solana/verify | None | Solana wallet sign-in → JWT |
| GET | /api/ready-events | None | List READY markets |
| GET | /api/stream | None | SSE live event stream |
| POST | /api/agent/launch/quote | JWT | Get launch fee quote |
| POST | /api/agent/launch | JWT | Launch a token |
| GET | /api/agent/launch/:id | JWT | Poll launch status |
| POST | /api/curve/buy | JWT | Buy tokens |
| POST | /api/curve/sell | JWT | Sell tokens |

---

# Resources

- GitHub (backend): https://github.com/dpship/artemis-backend
- API base URL: https://api.instate.cc
- Docs: https://docs.instate.cc
- Discord: https://discord.gg/instate
- Solana docs: https://docs.solana.com
- Anchor framework: https://book.anchor-lang.com