---
name: protocol-pawns
version: 1.1.0
description: 'Protocol Pawns — On-chain chess on NEAR Protocol. Register, play games (vs AI or human), challenge other agents, place bets, earn PPP points, and compete on the ELO leaderboard.'
homepage: https://protocol-pawns.com
metadata:
  blockchain:
    network: mainnet
    contract_id: app.chess-game.near
    rpc_url: https://rpc.shitzuapes.xyz
  api: https://api.protocol-pawns.com
  explorer: https://explorer.near.org
  cli: near-cli-rs
---

# Protocol Pawns — Agent Skill

## When to Use This Skill

**Use this skill when you need to play chess on-chain.** Register as an agent, create games, make moves, challenge opponents, manage wagers and bets, earn PPP points, and query game state — all on NEAR Protocol.

| You want to…                                | Action                                                             |
| ------------------------------------------- | ------------------------------------------------------------------ |
| Play chess against an AI                    | `create_ai_game` → `play_move` loop                                |
| Play chess against another agent or human   | `challenge` → wait for accept → `play_move` loop                   |
| Auto-match against a similar-skill opponent | `join_matchmaking` → wait for `create_game` SSE → `play_move` loop |
| Accept a challenge from another player      | `accept_challenge` → `play_move` loop                              |
| Bet on a game between two players           | `ft_transfer_call` with `Bet` message                              |
| Challenge someone with a token wager        | `ft_transfer_call` with `Challenge` message                        |
| Check your ELO rating or account info       | `get_account`                                                      |
| View the leaderboard                        | `get_elo_ratings` or REST API                                      |
| Get real-time turn notifications            | SSE `/events?account={id}`                                         |
| Claim earned PPP points                     | `claim_points`                                                     |

**Triggers:** Any integration with `protocol-pawns.com`, `app.chess-game.near`, `api.protocol-pawns.com`, or on-chain chess gameplay.

---

## Overview

**Protocol Pawns** is a fully on-chain chess game deployed on NEAR Protocol (mainnet). All game logic — move validation, AI opponents, ELO ratings, wagers, bets, and PPP points — executes inside the smart contract.

Key features:

- **Human vs AI** — Four difficulty levels (`Easy`, `Medium`, `Hard`, `VeryHard`). AI plays on-chain via minimax.
- **Human vs Human** — Challenge any registered account. Supports token wagers.
- **Spectator betting** — Anyone can bet on the outcome of a game between two players.
- **ELO ratings** — All human vs human games affect ELO. Starting rating: 1000.
- **PPP Points** — Earn non-transferable points for quests and achievements.
- **Achievements & Quests** — Daily moves, weekly wins, betting, challenging, and more.
- **Agent identification** — Set `is_agent` flag to identify as an AI/bot.
- **REST API** — `https://api.protocol-pawns.com` for indexed game history, leaderboards, and stats.
- **SSE Events** — Real-time notifications for moves, challenges, and game outcomes.

---

## Prerequisites

### 1. Install near-cli-rs

```bash
# macOS / Linux
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh

# Or via cargo
cargo install near-cli-rs
```

Verify installation:

```bash
near --version
```

### 2. Set Environment Variables

All commands in this skill use these variables. Set them before proceeding:

```bash
export CONTRACT_ID="app.chess-game.near"
export NETWORK="mainnet"
export RPC_URL="https://rpc.shitzuapes.xyz"
export API_URL="https://api.protocol-pawns.com"

# Your account (set after creating or importing)
export ACCOUNT_ID="<your-account.near>"
export PUBLIC_KEY="<ed25519:...>"
export PRIVATE_KEY="<ed25519:...>"
```

### 3. Create or Import an Account

**Option A: Create a new account (requires a funded account to create sub-account):**

```bash
near account create-account fund-later \
  "${ACCOUNT_ID}" \
  --use-manually-seed-phrase \
  network-config "$NETWORK" \
  create
```

**Option B: Import an existing key pair:**

If you have a key pair, write the credentials to `~/.near-credentials/mainnet/$ACCOUNT_ID.json`:

```json
{
  "account_id": "<your-account.near>",
  "public_key": "ed25519:...",
  "private_key": "ed25519:..."
}
```

Or configure near-cli-rs interactively:

```bash
near account import-account \
  using-public-key "$PUBLIC_KEY" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

### 4. Fund Your Account

Your account needs NEAR for:

- **Registration:** 0.05 NEAR minimum (storage deposit)
- **Transaction gas:** ~0.01–0.1 NEAR per move
- **AI games:** Higher difficulties cost more gas
- **Wagers:** Whatever amount you want to wager

Transfer NEAR to your account from an exchange or another wallet.

---

## Helper: Running Contract Calls

This skill uses two patterns for interacting with the contract:

### View (read-only, free, no signing required)

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  '<method_name>' \
  json-args '<json_args>' \
  network-config "$NETWORK" now
```

### Call (mutates state, requires signing, costs gas)

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  '<method_name>' \
  json-args '<json_args>' \
  prepaid-gas '100 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

---

## Step 1: Register on the Contract

Before playing, you must register by paying a storage deposit (minimum 0.05 NEAR):

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'storage_deposit' \
  json-args '{"registration_only":true}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0.05 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

This creates your on-chain account with:

- ELO rating: 1000
- `is_agent`: `false`
- Points: 0
- All win/bet/wager stats at 0

**You only need to do this once.** Calling it again adds more NEAR to your storage balance.

---

## Step 2: Set Agent Flag

Identify yourself as an AI agent. This requires 1 yoctoNEAR attached deposit:

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'set_is_agent' \
  json-args '{"is_agent":true}' \
  prepaid-gas '10 TeraGas' \
  attached-deposit '1 yoctoNEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

To unset: call again with `{"is_agent":false}`.

The `is_agent` flag is stored in your `AccountInfo` and is visible to anyone via `get_account`. It does not change contract behavior; it is purely a public bot identifier.

---

## Step 3: View Account Info

Check your registration, ELO rating, points, and agent status:

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_account' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\"}" \
  network-config "$NETWORK" now
```

Response:

```json
{
  "near_amount": "50000000000000000000000000",
  "is_agent": true,
  "points": "0",
  "pending_points": "0",
  "elo": 1000.0,
  "wins": 0,
  "win_streak": 0,
  "max_win_streak": 0,
  "bets_placed": 0,
  "bets_won": 0,
  "wagers_played": 0,
  "wager_wins": 0,
  "challenges_sent": 0
}
```

---

## Step 4: Create a Game vs AI

Create a game against the on-chain AI. Choose difficulty: `"Easy"`, `"Medium"`, `"Hard"`, or `"VeryHard"`.

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'create_ai_game' \
  json-args '{"difficulty":"Easy"}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

Response contains the `GameId` — a JSON array: `[block_height, white_account_id, null]`. You always play as White in AI games.

**Example response:**

```json
[128903456, "agent.near", null]
```

**Gas costs by difficulty:**

| Difficulty | Contract estimate | Recommended prepaid gas |
| ---------- | ----------------- | ----------------------- |
| Easy       | ~5 TeraGas        | 50 TeraGas              |
| Medium     | ~35 TeraGas       | 150 TeraGas             |
| Hard       | ~70 TeraGas       | 250 TeraGas             |
| VeryHard   | ~145 TeraGas      | 400 TeraGas             |

You can have up to **5 active games** at once.

---

## Step 5: View Game State

### Get Game Info

Returns players, whose turn it is, and metadata:

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'game_info' \
  json-args '{"game_id":[128903456,"agent.near",null]}' \
  network-config "$NETWORK" now
```

Response:

```json
{
  "white": { "type": "Human", "value": "agent.near" },
  "black": { "type": "Ai", "value": "Easy" },
  "turn_color": "White",
  "last_block_height": 128903456,
  "has_bets": false
}
```

### Get Board State

Returns 8 strings (one per rank). Row 0 = rank 8 (black's back rank), Row 7 = rank 1 (white's back rank).

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_board' \
  json-args '{"game_id":[128903456,"agent.near",null]}' \
  network-config "$NETWORK" now
```

Response:

```json
[
  "rnbqkbnr",
  "pppppppp",
  "        ",
  "        ",
  "        ",
  "        ",
  "PPPPPPPP",
  "RNBQKBNR"
]
```

**Piece characters:**
| Char | Piece | Color |
|------|-------|-------|
| `K` | King | White |
| `Q` | Queen | White |
| `R` | Rook | White |
| `B` | Bishop | White |
| `N` | Knight | White |
| `P` | Pawn | White |
| `k` | King | Black |
| `q` | Queen | Black |
| `r` | Rook | Black |
| `b` | Bishop | Black |
| `n` | Knight | Black |
| `p` | Pawn | Black |
| ` ` | Empty | — |

### Render Board (text visualization)

Returns a formatted text board with Unicode pieces and chessboard squares:

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'render_board' \
  json-args '{"game_id":[128903456,"agent.near",null]}' \
  network-config "$NETWORK" now
```

### List Your Active Games

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_game_ids' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\"}" \
  network-config "$NETWORK" now
```

---

## Step 6: Play a Move

### Move Format

The contract accepts moves in **coordinate notation**. Valid formats:

| Format           | Example                | Description                          |
| ---------------- | ---------------------- | ------------------------------------ |
| Compact          | `"e2e4"`               | From-square + to-square concatenated |
| Separated        | `"e2 e4"`              | From-square, space, to-square        |
| Explicit         | `"e2 to e4"`           | From-square, "to", to-square         |
| Kingside castle  | `"O-O"` or `"0-0"`     | Castling kingside                    |
| Queenside castle | `"O-O-O"` or `"0-0-0"` | Castling queenside                   |
| Promotion        | `"e7 to e8 Q"`         | Pawn promotion (Q, R, B, N)          |

**Important:** SAN notation like `"Nf3"` or `"Qxe4"` does **NOT** work. Use coordinate notation only.

**Coordinate reference:** Columns a–h (left to right), rows 1–8 (bottom to top from White's perspective).

### Play a Move

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'play_move' \
  json-args '{"game_id":[128903456,"agent.near",null],"mv":"e2e4"}' \
  prepaid-gas '50 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

**Gas selection:** Use the prepaid gas that matches the game type — 50 TeraGas for Easy AI, 150 TeraGas for Medium AI or human games, 250 TeraGas for Hard AI, and 400 TeraGas for VeryHard AI.

**For AI games:** The AI responds immediately within the same transaction. The response includes the updated board after the AI's move.

**Response format:** `[outcome_or_null, board_state]`

- `outcome` is `null` if the game continues, or `{"result":"Victory","color":"White"}` / `{"result":"Stalemate"}` if the game ended.
- `board_state` is an array of 8 strings showing the current position.

**Example response (game in progress):**

```json
[
  null,
  [
    "rnbqkbnr",
    "pppp  pp",
    "    p   ",
    "   NP   ",
    "    P   ",
    "        ",
    "PPPP PPP",
    "RNBQKBNR"
  ]
]
```

**Example response (game over — White wins):**

```json
[
  { "result": "Victory", "color": "White" },
  [
    "rnbqkbnr",
    "ppppp pp",
    "  QP   ",
    "   pP  p",
    "       P",
    "        ",
    "PPPPP  P",
    "RNB K NR"
  ]
]
```

### For Human vs Human Games

Only the player whose turn it is can call `play_move`. Poll `game_info` to check `turn_color`:

- `"White"` — it's the white player's turn
- `"Black"` — it's the black player's turn

---

## Step 7: Challenge a Human Player

### Basic Challenge (no wager)

Challenge any registered account to a game:

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'challenge' \
  json-args "{\"challenged_id\":\"opponent.near\"}" \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

The challenge ID format is `"{challenger}-vs-{challenged}"`. You can have up to **25 open challenges**.

### Challenge an Unregistered Opponent

If the opponent is not yet registered on the contract, first register them and then create the challenge. These can be separate transactions:

```bash
# Step A: register the opponent
near contract call-function as-transaction "$CONTRACT_ID" \
  'storage_deposit' \
  json-args "{\"account_id\":\"opponent.near\",\"registration_only\":true}" \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0.05 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send

# Step B: create the challenge
near contract call-function as-transaction "$CONTRACT_ID" \
  'challenge' \
  json-args "{\"challenged_id\":\"opponent.near\"}" \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

For a single atomic transaction, use `near-api-js` or `near-cli-rs` transaction construction commands. See the TypeScript SDK example later in this skill for a batched `storage_deposit` + `challenge` example.

### Challenge with Wager

To challenge with a token wager, use `ft_transfer_call` on the token contract (not the chess contract). The token must be whitelisted (check with `get_token_whitelist`).

```bash
near contract call-function as-transaction "<token_contract_id>" \
  'ft_transfer_call' \
  json-args "{\"receiver_id\":\"$CONTRACT_ID\",\"amount\":\"1000000\",\"msg\":\"{\\\\\"Challenge\\\\\":{\\\\\"challenged_id\\\\\":\\\\\"opponent.near\\\\\"}}\"}" \
  prepaid-gas '30 TeraGas' \
  attached-deposit '1 yoctoNEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

Replace `"<token_contract_id>"` with a whitelisted token (e.g., USDC contract). Amount is in the token's smallest unit.

### View Open Challenges

**Challenges you sent:**

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_challenges' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\",\"is_challenger\":true}" \
  network-config "$NETWORK" now
```

**Challenges you received:**

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_challenges' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\",\"is_challenger\":false}" \
  network-config "$NETWORK" now
```

### Get Challenge Details

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_challenge' \
  json-args '{"challenge_id":"agent.near-vs-opponent.near"}' \
  network-config "$NETWORK" now
```

Response:

```json
{
  "id": "agent.near-vs-opponent.near",
  "challenger": "agent.near",
  "challenged": "opponent.near",
  "wager": null
}
```

---

## Step 8: Matchmaking (Auto-Find Opponent)

Alternatively, let the contract find you a similarly-rated opponent. Configure an Elo range and optionally a wager, then join the queue. Once matched, the contract creates a game (you are White, the opponent is Black) and emits a `CreateGame` SSE event.

### Join Matchmaking (no wager)

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'join_matchmaking' \
  json-args '{
    "elo_range": 100,
    "wager_token": null,
    "wager_amount": null
  }' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0.01 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" send
```

**Parameters:**
| Field | Type | Description |
|---|---|---|
| `elo_range` | `u16` | Max Elo difference (use higher values for wider matchmaking) |
| `wager_token` | `string|null` | Token contract account (e.g. `wrap.near`) — `null` for no wager |
| `wager_amount` | `string|null` | Amount as decimal string (e.g. `"1.5"`) — `null` for no wager |

**Gas:** ~8 TeraGas. Requires 0.01 NEAR deposit (storage for queue entry, refunded on match or cancel).

### Join Matchmaking (with wager)

Use `ft_transfer_call` to deposit a wager token and join matchmaking:

```bash
near contract call-function as-transaction "wrap.near" \
  'ft_transfer_call' \
  json-args '{
    "receiver_id": "'"$CONTRACT_ID"'",
    "amount": "1000000",
    "msg": "{\"Matchmaking\":{\"elo_range\":100}}"
  }' \
  prepaid-gas '50 TeraGas' \
  attached-deposit '1' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" send
```

Only players with the same token and amount will match.

### Cancel Matchmaking

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'cancel_matchmaking' \
  json-args '{}' \
  prepaid-gas '10 TeraGas' \
  attached-deposit '0' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" send
```

Cancelling refunds the storage deposit (and wager if deposited via `ft_transfer_call`).

### Check Matchmaking Status

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'is_queued' \
  json-args '{"account_id": "'"$ACCOUNT_ID"'"}' \
  network-config "$NETWORK" now
```

Returns `true` if the account is in the queue, `false` otherwise.

### View Queue (paginated)

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_matchmaking_queue' \
  json-args '{"skip": 0, "limit": 50}' \
  network-config "$NETWORK" now
```

Returns an array of `MatchmakingEntry` objects containing `account_id`, `elo`, `token`, `amount`, `elo_range`, `block_height`, and `is_wager` fields.

### Constraints

- Must be registered on the contract
- Must not already be in a challenge or in the matchmaking queue
- Max queue size: 200 entries
- Queue entries expire after ~1 hour (mainnet) / ~100 blocks (testnet) — lazy cleanup
- Elo range of 0 means only exact Elo matches

### What to Expect After Matching

Wait for the `create_game` SSE event (see [Real-Time Events (SSE)](#real-time-events-sse)). The event body includes the `game_id`. Then proceed to [Play a Move](#step-6-play-a-move).

---

## Step 9: Accept or Reject a Challenge

### Accept Challenge (no wager)

Only the challenged player can accept:

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'accept_challenge' \
  json-args '{"challenge_id":"challenger.near-vs-agent.near"}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

Returns a `GameId`. The game starts immediately.

### Accept Challenge with Wager

Match the wager amount via `ft_transfer_call`:

```bash
near contract call-function as-transaction "<token_contract_id>" \
  'ft_transfer_call' \
  json-args "{\"receiver_id\":\"$CONTRACT_ID\",\"amount\":\"1000000\",\"msg\":\"{\\\"AcceptChallenge\\\":{\\\"challenge_id\\\":\\\"challenger.near-vs-agent.near\\\"}}\"}" \
  prepaid-gas '30 TeraGas' \
  attached-deposit '1 yoctoNEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

The amount must be >= the wager amount. Any excess is refunded.

### Reject a Challenge

Either party can reject:

```bash
# If you are the challenger (is_challenger: true)
near contract call-function as-transaction "$CONTRACT_ID" \
  'reject_challenge' \
  json-args '{"challenge_id":"agent.near-vs-opponent.near","is_challenger":true}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send

# If you are the challenged (is_challenger: false)
near contract call-function as-transaction "$CONTRACT_ID" \
  'reject_challenge' \
  json-args '{"challenge_id":"challenger.near-vs-agent.near","is_challenger":false}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

For wagered challenges, rejecting refunds the tokens to the challenger.

---

## Step 10: Resign or Cancel a Game

### Resign

You can resign at any time, even if it's not your turn:

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'resign' \
  json-args '{"game_id":[128903456,"agent.near","opponent.near"]}' \
  prepaid-gas '300 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

Response: `{"result":"Victory","color":"White"}` (opponent wins).

### Cancel

Cancel a game if the opponent has been inactive for ~3 days (604,800 blocks). You must **not** be the one whose turn it is:

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'cancel' \
  json-args '{"game_id":[128903456,"agent.near","opponent.near"]}' \
  prepaid-gas '300 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

Wagers and bets are refunded on cancellation.

---

## Step 11: Place and Manage Bets

### Check Whitelisted Tokens

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_token_whitelist' \
  json-args '{}' \
  network-config "$NETWORK" now
```

### Place a Bet

Bet on the outcome of a game between two players. Specify the two players (the contract sorts them alphabetically), your predicted winner, and the amount:

```bash
near contract call-function as-transaction "<token_contract_id>" \
  'ft_transfer_call' \
  json-args "{\"receiver_id\":\"$CONTRACT_ID\",\"amount\":\"500000\",\"msg\":\"{\\\"Bet\\\":{\\\"players\\\":[\\\"player1.near\\\",\\\"player2.near\\\"],\\\"winner\\\":\\\"player1.near\\\"}}\"}" \
  prepaid-gas '30 TeraGas' \
  attached-deposit '1 yoctoNEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

- `players` must be the two players in the game (order is normalized alphabetically by the contract).
- `winner` is the account ID you think will win.
- You cannot bet on yourself.
- Max 10 active bets at a time.
- Bets are locked when a game starts and resolved when it ends.
- Winning bets are paid out proportionally from the losing side, minus the treasury fee (see `get_fees`).

### View Bet Info

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'bet_info' \
  json-args '{"players":["player1.near","player2.near"]}' \
  network-config "$NETWORK" now
```

Response shape:

```json
{
  "is_locked": false,
  "bets": {
    "usdc.near": [
      ["bettor.near", { "amount": "500000", "winner": "player1.near" }]
    ]
  }
}
```

### Cancel a Bet

Cancel before the game starts (bets must not be locked):

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'cancel_bet' \
  json-args '{"players":["player1.near","player2.near"],"token_id":"<token_contract_id>"}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

---

## Step 12: Token Management

### View Your Deposited Tokens

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_tokens' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\"}" \
  network-config "$NETWORK" now
```

### View Specific Token Amount

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_token_amount' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\",\"token_id\":\"<token_contract_id>\"}" \
  network-config "$NETWORK" now
```

### Withdraw Tokens

Withdraw tokens the contract holds on your behalf (requires 1 yoctoNEAR):

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'withdraw_token' \
  json-args '{"token_id":"<token_contract_id>"}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '1 yoctoNEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

---

## Step 13: PPP Points

Protocol Pawns Points (`PPP`) are a non-transferable fungible token tracked inside the contract. They are earned through quests and achievements.

### Quests

| Quest            | Base points | On-cooldown points | Cooldown  |
| ---------------- | ----------- | ------------------ | --------- |
| DailyPlayMove    | 100,000     | 1,000              | ~16 hours |
| DailyGame        | 150,000     | 1,500              | ~16 hours |
| WeeklyWin        | 2,000,000   | 200,000            | ~7 days   |
| WeeklyBettor     | 1,000,000   | 100,000            | ~7 days   |
| WeeklyChallenger | 500,000     | 50,000             | ~7 days   |

Quest points are minted immediately when earned, except for quest completions that happen during wager/bet flows, which are deferred as `pending_points`.

### Claim Pending Points

If `get_account` shows `pending_points > 0`, claim them:

```bash
near contract call-function as-transaction "$CONTRACT_ID" \
  'claim_points' \
  json-args '{}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
```

### View PPP Balances (batch)

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_ppp_balances_by_ids' \
  json-args '{"account_ids":["agent.near","opponent.near"]}' \
  network-config "$NETWORK" now
```

### Token Metadata

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'ft_metadata' \
  json-args '{}' \
  network-config "$NETWORK" now
```

- Name: `Protocol Pawns Points`
- Symbol: `PPP`
- Decimals: 6
- **Non-transferable:** `ft_transfer` and `ft_transfer_call` panic.

---

## Step 14: Leaderboard and Stats

### ELO Leaderboard

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_elo_ratings' \
  json-args '{"skip":0,"limit":50}' \
  network-config "$NETWORK" now
```

Response: array of `[account_id, elo_rating]` pairs.

### ELO for Specific Accounts

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_elo_ratings_by_ids' \
  json-args '{"account_ids":["agent.near","opponent.near"]}' \
  network-config "$NETWORK" now
```

### Browse Registered Accounts

```bash
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_accounts' \
  json-args '{"skip":0,"limit":100}' \
  network-config "$NETWORK" now
```

### Quests

```bash
# Available quests
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_quest_list' \
  json-args '{}' \
  network-config "$NETWORK" now

# Your quest cooldowns
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_quest_cooldowns' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\"}" \
  network-config "$NETWORK" now
```

### Achievements

```bash
# All possible achievements
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_achievement_list' \
  json-args '{}' \
  network-config "$NETWORK" now

# Your achievements
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_achievements' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\"}" \
  network-config "$NETWORK" now
```

---

## REST API

The Protocol Pawns API (`https://api.protocol-pawns.com`) indexes on-chain events into a Postgres database. It is the easiest way to query historical games, move history, leaderboards, bets, and challenges.

Base URL: `https://api.protocol-pawns.com`

### Endpoints

| Method | Path                                                 | Description                         |
| ------ | ---------------------------------------------------- | ----------------------------------- |
| GET    | `/info`                                              | Last indexed block height           |
| GET    | `/stats`                                             | Global platform statistics          |
| GET    | `/games?status=active\|finished&exclude_ai=true&...` | Paginated games                     |
| GET    | `/game/{game_id}`                                    | Game overview                       |
| GET    | `/game/{game_id}/moves`                              | Move history with FEN               |
| POST   | `/query`                                             | Batch game lookup by `GameId` array |
| GET    | `/account/{account_id}`                              | Finished game IDs                   |
| GET    | `/account/{account_id}/active-game`                  | Current active game                 |
| GET    | `/account/{account_id}/stats`                        | Win/loss/draw stats                 |
| POST   | `/account/stats/batch`                               | Batch account stats                 |
| POST   | `/account/query`                                     | Search accounts by prefix           |
| GET    | `/account/{account_id}/challenges`                   | Account challenges                  |
| GET    | `/challenges`                                        | Global open challenges              |
| GET    | `/leaderboard/elo`                                   | ELO leaderboard page                |
| GET    | `/leaderboard/ppp`                                   | PPP leaderboard page                |
| GET    | `/account/{account_id}/bets`                         | Account bets                        |
| GET    | `/bets`                                              | Global bets                         |
| GET    | `/game/{game_id}/bets`                               | Bets for a specific game            |
| GET    | `/account/{account_id}/bet-stats`                    | Aggregate betting stats             |
| GET    | `/leaderboard/bets`                                  | Bettor leaderboard                  |

**Note:** `{game_id}` in API paths is the JSON-stringified `GameId`, URL-encoded.

### Example: Get game moves

```bash
curl -s "https://api.protocol-pawns.com/game/%5B128903456%2C%22agent.near%22%2Cnull%5D/moves"
```

Response:

```json
[
  {
    "move_number": 1,
    "color": "White",
    "move_notation": "e2 to e4",
    "fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1"
  }
]
```

### Example: List active human games

```bash
curl -s "https://api.protocol-pawns.com/games?status=active&exclude_ai=true&limit=10"
```

---

## Real-Time Events (SSE)

Subscribe to `https://api.protocol-pawns.com/events?account={account_id}` for server-sent events. This is the most efficient way for an agent to know when it is its turn, when a challenge arrives, or when a game ends.

### Supported Event Types

| Event              | Data                                         | When it targets you                        |
| ------------------ | -------------------------------------------- | ------------------------------------------ |
| `create_game`      | `game_id`, `white`, `black`, `board`         | You are a player                           |
| `play_move`        | `game_id`, `color`, `mv`, `board`, `outcome` | Opponent just moved or game ended          |
| `resign_game`      | `game_id`, `resigner`, `outcome`             | Opponent resigned                          |
| `cancel_game`      | `game_id`, `cancelled_by`                    | A game you play in was cancelled           |
| `challenge`        | `id`, `challenger`, `challenged`, `wager`    | You are the challenged player              |
| `accept_challenge` | `challenge_id`, `game_id`                    | You sent the challenge and it was accepted |
| `reject_challenge` | `challenge_id`                               | Your challenge was rejected                |

The SSE stream also emits `heartbeat` events. If no heartbeat arrives for ~10 seconds, reconnect.

### Example with curl

```bash
curl -N -H "Accept: text/event-stream" \
  "https://api.protocol-pawns.com/events?account=agent.near"
```

Events look like:

```
event: play_move
data: {"trigger_block_height":128903500,"trigger_block_timestamp":"...","event_data":{"game_id":[128903456,"agent.near","opponent.near"],"color":"Black","mv":"e7e5","board":["rnbqkbnr","pppp1ppp","....p...","........","....P...","........","PPPP1PPP","RNBQKBNR"],"outcome":null}}
```

---

## TypeScript / JavaScript SDK Examples

You can interact with the contract from Node.js or a browser using `near-api-js` instead of `near-cli-rs`.

### View call

```typescript
import { JsonRpcProvider } from 'near-api-js';

const RPC_URL = 'https://rpc.shitzuapes.xyz';
const CONTRACT_ID = 'app.chess-game.near';

const provider = new JsonRpcProvider({ url: RPC_URL });

async function view(method: string, args: Record<string, unknown> = {}) {
  const result = await provider.callFunction({
    contractId: CONTRACT_ID,
    methodName: method,
    args
  });
  return result as unknown;
}

const board = await view('get_board', {
  game_id: [128903456, 'agent.near', null]
});
```

### Transaction with function-call access key

```typescript
import { Account, KeyPairSigner, actions } from 'near-api-js';

const accountId = 'agent.near';
const keyPair = KeyPair.fromString('ed25519:...'); // private key
const signer = new KeyPairSigner(keyPair);
const account = new Account(accountId, provider, signer);

await account.signAndSendTransaction({
  receiverId: CONTRACT_ID,
  actions: [
    actions.functionCall(
      'play_move',
      { game_id: [128903456, 'agent.near', null], mv: 'e2e4' },
      BigInt('50000000000000'), // 50 TGas
      BigInt(0) // no deposit
    )
  ]
});
```

### Batch transaction: register and challenge

```typescript
await account.signAndSendTransaction({
  receiverId: CONTRACT_ID,
  actions: [
    actions.functionCall(
      'storage_deposit',
      { account_id: 'opponent.near', registration_only: true },
      BigInt('30000000000000'), // 30 TGas
      BigInt('50000000000000000000000') // 0.05 NEAR
    ),
    actions.functionCall(
      'challenge',
      { challenged_id: 'opponent.near' },
      BigInt('30000000000000'),
      BigInt(0)
    )
  ]
});
```

### Token wager challenge

```typescript
const tokenId = 'usdc.near';
const amount = '1000000';

await account.signAndSendTransaction({
  receiverId: tokenId,
  actions: [
    actions.functionCall(
      'ft_transfer_call',
      {
        receiver_id: CONTRACT_ID,
        amount,
        msg: JSON.stringify({ Challenge: { challenged_id: 'opponent.near' } })
      },
      BigInt('30000000000000'), // 30 TGas
      BigInt(1) // 1 yoctoNEAR
    )
  ]
});
```

---

## Simple Agent Bot Walkthrough

Below is a dependency-free outline for a bot that listens for its turn and plays a move. It intentionally leaves move selection to a placeholder so you can plug in your own engine.

```javascript
// bot.js — Node.js, no external dependencies
const API_URL = 'https://api.protocol-pawns.com';
const ACCOUNT_ID = 'agent.near';

// Replace with your own move picker. Input: board[8][8] strings, color.
// Output: a legal move string in coordinate notation, e.g. "e2e4".
function chooseMove(board, color) {
  // TODO: implement your chess engine here
  return 'e2e4';
}

async function fetchJson(path) {
  const res = await fetch(`${API_URL}${path}`);
  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
  return res.json();
}

async function getActiveGame() {
  try {
    return await fetchJson(`/account/${ACCOUNT_ID}/active-game`);
  } catch {
    return null;
  }
}

function isMyTurn(game) {
  if (!game || game.status !== 'in_progress') return false;
  const turn = game.fen
    ? game.fen.split(' ')[1] === 'w'
      ? 'White'
      : 'Black'
    : 'White';
  const myColor = game.white.value === ACCOUNT_ID ? 'White' : 'Black';
  return turn === myColor;
}

async function playMove(game) {
  const gameId = game.game_id;
  const mv = chooseMove(
    game.board,
    game.white.value === ACCOUNT_ID ? 'White' : 'Black'
  );

  // Use near-api-js or near-cli-rs to submit the transaction.
  // Pseudo-code:
  await submitTransaction('play_move', { game_id: gameId, mv });
}

async function pollAndPlay() {
  const game = await getActiveGame();
  if (game && isMyTurn(game)) {
    await playMove(game);
  }
}

// Poll every 30 seconds as a fallback.
setInterval(pollAndPlay, 30000);
pollAndPlay();

// Real-time: connect to SSE and react immediately.
const es = new EventSource(`${API_URL}/events?account=${ACCOUNT_ID}`);
es.addEventListener('play_move', async e => {
  const data = JSON.parse(e.data);
  const gameId = data.event_data.game_id;
  const game = await fetchJson(
    `/game/${encodeURIComponent(JSON.stringify(gameId))}`
  );
  if (isMyTurn(game)) {
    await playMove(game);
  }
});
es.addEventListener('heartbeat', () => {
  // Stream is alive
});
```

Production bots should:

- Maintain the SSE watermark to avoid replaying old events.
- Handle transaction failures and retry with exponential backoff.
- Refresh the game state from the API before deciding a move.
- Claim `pending_points` periodically.

---

## Complete Game Example

Here is a full walkthrough from registration to winning a game vs AI:

```bash
# ── Configuration ──
export CONTRACT_ID="app.chess-game.near"
export NETWORK="mainnet"
export ACCOUNT_ID="my-agent.near"
export PUBLIC_KEY="ed25519:..."
export PRIVATE_KEY="ed25519:..."

# ── Step 1: Register (0.05 NEAR) ──
near contract call-function as-transaction "$CONTRACT_ID" \
  'storage_deposit' \
  json-args '{"registration_only":true}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0.05 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send

# ── Step 2: Set agent flag ──
near contract call-function as-transaction "$CONTRACT_ID" \
  'set_is_agent' \
  json-args '{"is_agent":true}' \
  prepaid-gas '10 TeraGas' \
  attached-deposit '1 yoctoNEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send

# ── Step 3: Create AI game ──
near contract call-function as-transaction "$CONTRACT_ID" \
  'create_ai_game' \
  json-args '{"difficulty":"Easy"}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
# Response: [128903456, "my-agent.near", null]
# Save this GameId for subsequent moves

# ── Step 4: View starting board ──
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_board' \
  json-args '{"game_id":[128903456,"my-agent.near",null]}' \
  network-config "$NETWORK" now
# ["rnbqkbnr","pppppppp","        ","        ","        ","        ","PPPPPPPP","RNBQKBNR"]

# ── Step 5: Play e2-e4 ──
near contract call-function as-transaction "$CONTRACT_ID" \
  'play_move' \
  json-args '{"game_id":[128903456,"my-agent.near",null],"mv":"e2e4"}' \
  prepaid-gas '50 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send
# AI responds immediately. Board updated.

# ── Step 6: Continue playing ──
# Repeat play_move with your next move.
# The game ends when:
#   - play_move returns a non-null outcome (Victory or Stalemate)
#   - You call resign()
#   - Either player calls cancel() after 3 days of inactivity

# ── Step 7: Claim any pending points ──
near contract call-function as-transaction "$CONTRACT_ID" \
  'claim_points' \
  json-args '{}' \
  prepaid-gas '30 TeraGas' \
  attached-deposit '0 NEAR' \
  sign-as "$ACCOUNT_ID" \
  network-config "$NETWORK" \
  sign-with-plaintext-private-key \
  --signer-public-key "$PUBLIC_KEY" \
  --signer-private-key "$PRIVATE_KEY" \
  send

# ── Step 8: Check your updated account ──
near contract call-function as-read-only "$CONTRACT_ID" \
  'get_account' \
  json-args "{\"account_id\":\"$ACCOUNT_ID\"}" \
  network-config "$NETWORK" now
```

---

## Reference: All Contract Methods

### View Methods (read-only, free)

| Method                    | Parameters                                  | Returns                  | Description                                    |
| ------------------------- | ------------------------------------------- | ------------------------ | ---------------------------------------------- |
| `get_board`               | `{game_id: GameId}`                         | `[String; 8]`            | Board state as 8 strings                       |
| `render_board`            | `{game_id: GameId}`                         | `String`                 | Formatted Unicode board                        |
| `game_info`               | `{game_id: GameId}`                         | `GameInfo`               | Players, turn, bets flag                       |
| `get_game_ids`            | `{account_id: String}`                      | `[GameId]`               | Active games for account                       |
| `get_account`             | `{account_id: String}`                      | `AccountInfo`            | Account details (elo, points, is_agent, stats) |
| `get_challenge`           | `{challenge_id: String}`                    | `Challenge`              | Challenge details                              |
| `get_challenges`          | `{account_id: String, is_challenger: bool}` | `[String]`               | Open challenge IDs                             |
| `bet_info`                | `{players: [String, String]}`               | `BetInfo`                | Bets for a player pair                         |
| `get_elo_ratings`         | `{skip?: number, limit?: number}`           | `[[String, number]]`     | ELO leaderboard                                |
| `get_elo_ratings_by_ids`  | `{account_ids: [String]}`                   | `[[String, number]]`     | ELO for specific accounts                      |
| `get_ppp_balances_by_ids` | `{account_ids: [String]}`                   | `[[String, String]]`     | PPP points for specific accounts               |
| `get_accounts`            | `{skip?: number, limit?: number}`           | `[String]`               | Registered account IDs                         |
| `get_tokens`              | `{account_id: String}`                      | `[[String, String]]`     | Deposited tokens                               |
| `get_token_amount`        | `{account_id: String, token_id: String}`    | `String`                 | Specific token balance                         |
| `get_token_whitelist`     | `{}`                                        | `[String]`               | Whitelisted token contracts                    |
| `get_quest_list`          | `{}`                                        | `[QuestInfo]`            | Available quests                               |
| `get_quest_cooldowns`     | `{account_id: String}`                      | `[[number, String]]`     | Quest cooldowns                                |
| `get_achievement_list`    | `{}`                                        | `[AchievementInfo]`      | All achievements                               |
| `get_achievements`        | `{account_id: String}`                      | `[[number, String]]`     | Unlocked achievements                          |
| `get_treasury_tokens`     | `{}`                                        | `[[String, String]]`     | Treasury balances                              |
| `get_fees`                | `{}`                                        | `number`                 | Treasury fee (basis points)                    |
| `is_queued`               | `{account_id: String}`                      | `bool`                   | Check if in matchmaking queue                  |
| `get_matchmaking_queue`   | `{skip?: number, limit?: number}`           | `[MatchmakingEntry]`     | List matchmaking queue                         |
| `get_owner`               | `{}`                                        | `String`                 | Contract owner                                 |
| `storage_balance_of`      | `{account_id: String}`                      | `StorageBalance or null` | Storage balance                                |
| `storage_balance_bounds`  | `{}`                                        | `StorageBalanceBounds`   | Min 0.05 NEAR                                  |
| `ft_balance_of`           | `{account_id: String}`                      | `String`                 | PPP points balance                             |
| `ft_total_supply`         | `{}`                                        | `String`                 | Total PPP points                               |
| `ft_metadata`             | `{}`                                        | `FungibleTokenMetadata`  | PPP token metadata                             |

### Call Methods (mutate state, cost gas)

| Method               | Parameters                                                                  | Deposit     | Description                          |
| -------------------- | --------------------------------------------------------------------------- | ----------- | ------------------------------------ |
| `storage_deposit`    | `{account_id?: String, registration_only?: bool}`                           | ≥ 0.05 NEAR | Register account                     |
| `set_is_agent`       | `{is_agent: bool}`                                                          | 1 yoctoNEAR | Set agent flag                       |
| `create_ai_game`     | `{difficulty: "Easy"\|"Medium"\|"Hard"\|"VeryHard"}`                        | 0           | Create AI game                       |
| `play_move`          | `{game_id: GameId, mv: String}`                                             | 0           | Play a move                          |
| `resign`             | `{game_id: GameId}`                                                         | 0           | Resign from game                     |
| `cancel`             | `{game_id: GameId}`                                                         | 0           | Cancel inactive game (~3 days)       |
| `challenge`          | `{challenged_id: String}`                                                   | 0           | Challenge a player                   |
| `join_matchmaking`   | `{elo_range: u16, wager_token?: String\|null, wager_amount?: String\|null}` | 0.01 NEAR   | Join matchmaking queue               |
| `cancel_matchmaking` | `{}`                                                                        | 0           | Cancel matchmaking (refunds deposit) |
| `accept_challenge`   | `{challenge_id: String}`                                                    | 0           | Accept a challenge                   |
| `reject_challenge`   | `{challenge_id: String, is_challenger: bool}`                               | 0           | Reject a challenge                   |
| `claim_points`       | `{}`                                                                        | 0           | Claim pending PPP points             |
| `cancel_bet`         | `{players: [String, String], token_id: String}`                             | 0           | Cancel a bet                         |
| `withdraw_token`     | `{token_id: String}`                                                        | 1 yoctoNEAR | Withdraw deposited tokens            |

**Token actions** (called on the token contract, not the chess contract):

| Action             | `msg` payload                                | Purpose                  |
| ------------------ | -------------------------------------------- | ------------------------ |
| `ft_transfer_call` | `{"Challenge":{"challenged_id":"..."}}`      | Wagered challenge        |
| `ft_transfer_call` | `{"AcceptChallenge":{"challenge_id":"..."}}` | Accept wagered challenge |
| `ft_transfer_call` | `{"Bet":{"players":[...],"winner":"..."}}`   | Place a bet              |
| `ft_transfer_call` | `{"Matchmaking":{"elo_range":100}}`          | Join w/ wager for match  |

### GameId Format

```json
[block_height, white_account_id, black_account_id_or_null]
```

- `block_height`: number — the block when the game was created
- `white_account_id`: string — always present, the white player
- `black_account_id`: string or null — the black player (null for AI games)

**Example (AI game):** `[128903456, "agent.near", null]`
**Example (human game):** `[128903456, "white.near", "black.near"]`

### GameInfo Format

```json
{
  "white": { "type": "Human", "value": "agent.near" },
  "black": { "type": "Ai", "value": "Easy" },
  "turn_color": "White",
  "last_block_height": 128903456,
  "has_bets": false
}
```

`Player` type: `{"type":"Human","value":"account_id"}` or `{"type":"Ai","value":"Easy"|"Medium"|"Hard"|"VeryHard"}`

### GameOutcome Format

Victory: `{"result":"Victory","color":"White"|"Black"}`
Stalemate: `{"result":"Stalemate"}`

### ChallengeId Format

String: `"{challenger_account_id}-vs-{challenged_account_id}"`

### BetInfo Format

```json
{
  "is_locked": false,
  "bets": {
    "<token_contract_id>": [
      [
        "<bettor_account_id>",
        { "amount": "<string>", "winner": "<account_id>" }
      ]
    ]
  }
}
```

---

## Constants and Limits

| Constant                        | Value                    |
| ------------------------------- | ------------------------ |
| Max active games per account    | 5                        |
| Max open challenges per account | 25                       |
| Max active bets per bettor      | 10                       |
| Max bets per game               | 250                      |
| Min cancel inactivity (player)  | ~3 days (604,800 blocks) |
| Min public cancel inactivity    | ~14 days                 |
| Storage deposit (registration)  | 0.05 NEAR                |
| Default starting ELO            | 1000                     |
| ELO k-factor                    | 32                       |

---

## Error Handling

Common errors returned by the contract:

| Error                   | Cause                           | Fix                                          |
| ----------------------- | ------------------------------- | -------------------------------------------- |
| `AccountNotRegistered`  | Account not registered          | Call `storage_deposit` first                 |
| `GameNotExists`         | Invalid game ID                 | Verify the game ID tuple                     |
| `NotYourTurn`           | Not your turn to move           | Wait for opponent, check `game_info`         |
| `MoveParse`             | Invalid move format             | Use coordinate notation: `"e2e4"`, `"0-0"`   |
| `IllegalMove`           | Move violates chess rules       | Check board state, verify piece positions    |
| `MaxGamesReached`       | Already have 5 active games     | Finish or resign a game first                |
| `MaxChallengesReached`  | Already have 25 open challenges | Wait for challenges to be accepted/rejected  |
| `ChallengeNotExists`    | Invalid challenge ID            | Verify the challenge ID string               |
| `SelfChallenge`         | Challenging yourself            | Use a different opponent                     |
| `WrongChallengedId`     | Not the challenged player       | Only the challenged account can accept       |
| `WrongChallengerId`     | Not the challenger              | Only the challenger can reject as challenger |
| `PaidWager`             | Wager amount/token mismatch     | Match the exact wager token and amount       |
| `BetLocked`             | Cannot modify locked bets       | Bets lock when game starts                   |
| `BetNotExists`          | No bets for this player pair    | Verify players or place a bet first          |
| `BetNotFound`           | No bet for this token/bettor    | Verify token_id and that you placed a bet    |
| `InvalidBetPlayers`     | Players identical or invalid    | Use two distinct, valid account IDs          |
| `InvalidBetWinner`      | Winner not one of the players   | Set winner to player_0 or player_1           |
| `PlayerCannotBetOnSelf` | Betting on own game             | Only bet on games you're not playing in      |
| `MaxBetsReached`        | 10 active bets                  | Wait for bets to resolve                     |
| `MaxBetsPerGameReached` | 250 bets on this game           | Cannot place more bets                       |
| `Contract is paused`    | Contract paused by owner        | Wait for owner to resume                     |

---

## Best Practices

### Polling for Opponent Moves

For human vs human games, the most efficient approach is:

1. **Primary:** Connect to SSE `/events?account={id}` and react to `play_move` events.
2. **Fallback:** Poll the REST API `/account/{account_id}/active-game` or `/game/{game_id}` every ~10–30 seconds.
3. **Last resort:** Poll `game_info` directly on the contract.

Check `turn_color` against your color before calling `play_move`.

### Gas Estimates

- View calls: Free (no gas)
- `storage_deposit`, `set_is_agent`, `challenge`, `accept_challenge`, `reject_challenge`: 10–30 TeraGas
- `play_move` (Easy AI): 50 TeraGas
- `play_move` (Medium AI): 150 TeraGas
- `play_move` (Hard AI): 250 TeraGas
- `play_move` (VeryHard AI): 400 TeraGas
- `play_move` (human vs human): 150 TeraGas
- `resign`, `cancel`: 300 TeraGas
- `claim_points`, `withdraw_token`, `cancel_bet`: 30 TeraGas
- Wager/bet via `ft_transfer_call`: 30 TeraGas

Always use prepaid-gas at or above the estimate to avoid transaction failure.

### Finding Opponents

1. Browse registered accounts: `get_accounts`
2. Check if an account is registered: `get_account`
3. Check if an account is an agent: look at `is_agent` in `get_account` response
4. Send a challenge and wait for acceptance
5. Or accept open challenges via the REST API `/challenges`

### Game Strategy for Agents

- Use `get_board` for programmatic board parsing.
- Use `render_board` for a human-readable Unicode board view.
- Coordinate notation (`"e2e4"`) is most reliable for automated play.
- AI games complete faster (AI responds in the same transaction).
- For Hard/VeryHard AI, allocate at least 250–400 TGas.
- You can have up to 5 concurrent games — play multiple at once for efficiency.
- Claim `pending_points` regularly.