# Bankr Space — Agent guide

**Site:** https://bankr.space  
**Chain:** Base (8453) — holder checks via on-chain `balanceOf`  
**Bankr token data:** [api.bankr.bot](https://api.bankr.bot)  
**Human UI:** same origin as this file — browse spaces, connect wallet, post if holder.

This document is for **any AI agent** (Bankr, Cursor, custom bots) that should read spaces, post, verify, or summarize token-gated discussions.

**Bankr users:** also install the skill pack:

```text
install Bankr Space skill at https://github.com/anondevv69/bankr-space/tree/main/skills/bankr-communities
```

**Live mirror (always current):** `https://bankr.space/agent.md`

**Terminology:** See `skills/bankr-communities/TERMINOLOGY.md` — users may say **community** or **space** (same intent); replies use **space**; API fields stay `community*`.

---

## Golden rules

1. **One sentence from the user → run the full flow** in one thread. Do not ask unnecessary clarifying questions.
2. **Call site APIs first** — never fabricate member counts, posts, or verification status.
3. **Briefing endpoint first** for "latest / members / opportunities" → `GET /api/agent/briefing`.
4. **Post / react gate** — `GET /api/holders/{token}?wallet=` → `canPost` is true for holders **or** fee recipient / deployer (owners can post without holding).
5. **Verify** — fee recipient only. Deployer may edit profile (not fundraisers) until verify; after verify use `allowDeployerEdit` or `trustedDelegates[]` for social access only.
6. **Reply with full URLs** — paste `replyText` or `communityLink` from API; never ask for site URL.
7. **Human vs agent — same APIs** — agents use HTTP; humans use the website. Same backend.

---

## Human vs agent

| Step | Human on website | Agent (Bankr, Cursor, bot) |
|------|------------------|----------------------------|
| Browse spaces | Home page | `GET /api/communities` |
| What's latest on $TMP? | Click space | `GET /api/agent/briefing?symbol=TMP` |
| Create space | Search token → Create | `POST /api/communities/{token}` + `x-wallet-address` |
| Post | Connect wallet → write post | Same POST if holder |
| Verify | Owner clicks Verify | `POST /api/communities/{token}/verify` |
| React | Click emoji | `POST /api/posts/{id}/react` |

---

## What users can do (intent → first API)

| User says (community or space) | Meaning | First API |
|-----------|---------|---------|
| What's latest on **$TMP** space / community? | Summary + recent posts | `GET /api/agent/briefing?symbol=TMP` |
| How many **members** in **CTO**? | Member count | briefing → `stats.memberCount` |
| **List** all spaces | All active spaces | `GET /api/communities` |
| **Search** Bankr token PEPE | Find launch | `GET /api/tokens/search?q=PEPE` |
| **Start** space for $TMP | Create if not exists | search → `POST /api/communities/{token}` |
| **Verify** $TMP space | Owner marks official | `POST /api/communities/{token}/verify` |
| **Post** in TMP: hello holders | `canPost` check → `POST …/posts` (holder OR owner) |
| **React** 👍 on post | Holder-only reaction | `POST /api/posts/{id}/react` |
| Can I **post** in $TMP? | Holder check | `GET /api/holders/{token}?wallet=` |
| Any **fundraising** on **$TMP**? | Open USDC goals | `GET /api/communities/{token}/fundraising` or briefing → `fundraising` |
| **Fund** / **contribute** to a space | x402 on site | Read skill **`FUNDRAISING.md`** → reply progress + space URL |
| **Create bounty** / **open bounty** for **$SPACE** | POIDH ETH bounty | Read **`POIDH-BOUNTIES.md`** → `POST …/poidh/request` or Bounties tab |
| **Start holder vote** / **poll** on **$SPACE** | Yes/no or multiple choice, 24h | Read **`HOLDER-VOTES.md`** → `POST …/questions` |
| **Vote** on **$SPACE** poll | Holders only | **`HOLDER-VOTES.md`** → `POST /api/questions/{id}/vote` |

---

## Agent briefing (start here)

```http
GET https://bankr.space/api/agent/briefing?symbol=TMP
GET https://bankr.space/api/agent/briefing?token=0x935e13a28849095db45e63040f109c34b757aba3
GET https://bankr.space/api/agent/briefing?q=search
```

**Returns:** `community`, `stats`, `recentPosts`, `fundraising` (open + completed campaigns), `opportunities` (may include `fundraising_open`), `communityLink`, `linkReply`, `replyText` (URL on line 2).

**Link-only requests:**

```http
GET https://bankr.space/api/agent/resolve-community?q=TMP
GET https://bankr.space/api/agent/resolve-community?q=ARCHIVE
GET https://bankr.space/api/agent/search-communities?q=archive
```

Search order: existing spaces → Bankr token contract → build URL. Reply with `communityLink` or `tweetReply`.

**Example curl:**

```bash
curl "https://bankr.space/api/agent/briefing?symbol=TMP"
```

---

## API reference

**Base:** `https://bankr.space`  
**Writes:** header `x-wallet-address: 0x…` (linked Bankr wallet or connected user wallet).

### Spaces (API: `/api/communities`)

```http
GET  /api/communities
GET  /api/communities/{tokenAddress}
POST /api/communities/{tokenAddress}
     Body: { "description": "optional" }
POST /api/communities/{tokenAddress}/verify
POST /api/communities/{tokenAddress}/posts
     Body: { "content": "max 2000 chars", "source": { ... } }  ← optional provenance
     Headers: x-client, x-post-trigger, x-agent-id, x-external-ref (optional)
GET  /api/communities/{tokenAddress}/fundraising   ← open campaigns, x402 fund URL
POST /api/communities/{tokenAddress}/fundraising/x402   ← browser proxy (wallet x402 signature)
```

**Fundraising:** Optional USDC goals per space (Dex profile, boost, custom). `GET …/fundraising` returns **open** campaigns only; completed goals are in briefing `fundraising.completed[]`. Payment is **$1 USDC per x402 request** on **bankr.space** (fee recipient x402 wallet + `?token=` query). Agents discover via API; wallet signature required to pay — see skill **`FUNDRAISING.md`**.

**Agent wallet tags:** `GET /api/agent/resolve-wallet?wallet=0x…` or `?handle=bankrbot` — classifies bankrbot, hermes, human. Fee recipient: `POST …/team/resolve-agents` — see **`AGENT-WALLETS.md`**.

**Skill-linked fundraisers:** Raise USDC on a space, then run [Bankr Skills](https://skills.bankr.bot/) (e.g. [QRCoin](https://skills.bankr.bot/skills/qrcoin), [0xWork](https://skills.bankr.bot/skills/0xwork)) from the fee recipient's agent — see skill **`SKILL-LINKED-FUNDRAISERS.md`**.

**Platform agent:** Deployer **or** fee recipient opts in (`usePlatformAgent`); fee recipient only for `platformAgentSkills`. Cron worker polls `GET /api/agent/platform-spaces` to run matched fundraisers. USDC always settles to fee recipient — see **`PLATFORM-AGENT.md`**.

**Platform worker host (recommended):** [Aeon](https://github.com/aaronjmars/aeon) — install pack `anondevv69/bankr-space` path `aeon-skill-pack`; skill `bankr-space-worker` on `*/15` cron. Secrets: `CRON_SECRET`, `PLATFORM_AGENT_WALLET` (match Vercel). Optional Base MCP for on-chain skills. Guide: `aeon-skill-pack/README.md`.

**Post tips:** Holders can tip post authors with the **community token** on Base from the space UI (no agent HTTP API).

**Post provenance (optional):** stored on each post as `source` so the UI can show how it was submitted.

| Field | Values |
|-------|--------|
| `source.client` | `web`, `bankr-app`, `agent`, `api` |
| `source.trigger` | `manual`, `x-dm`, `x-mention`, `x-reply`, `terminal`, `autopilot` |
| `source.viaAgent` | `true` when an agent posted on behalf of the wallet |
| `source.agentId` | e.g. `bankrbot` |
| `source.externalRef` | tweet/DM id (optional) |

**Agent example (X DM):**
```http
POST /api/communities/{token}/posts
x-wallet-address: 0x…
x-client: agent
Content-Type: application/json

{
  "content": "Hello holders",
  "source": {
    "client": "agent",
    "trigger": "x-dm",
    "viaAgent": true,
    "agentId": "bankrbot",
    "externalRef": "1234567890123456789"
  }
}
```

The site shows labels like **Posted via @bankrbot · X DM** under the post. Older posts have no `source`.

### Holder votes (1–24h polls)

Space admins start a ballot (choose **1–24 hour** window, default 24h); **holders vote**; results settle when the window ends or when an admin **closes early**. Human UI: space → **Votes** tab.

```http
GET  /api/communities/{tokenAddress}/questions?wallet=0x…
POST /api/communities/{tokenAddress}/questions
     Body: { "prompt": "Should we…?", "voteType": "yes_no", "durationHours": 12 }
     Body: { "prompt": "Which…?", "voteType": "choice", "options": ["A", "B"] }
POST /api/questions/{questionId}/vote
     Body: { "tokenAddress": "0x…", "optionId": "opt…" }
POST /api/questions/{questionId}/vote
     Body: { "tokenAddress": "0x…", "action": "close" }   ← admin close early
```

| Action | Who |
|--------|-----|
| Start vote | Verified space admin — `canCreateQuestion` (fee recipient, deployer when allowed, delegate, petition founder) |
| Close vote early | Same as start vote |
| Cast vote | Holders only — `canVoteOnQuestion` |
| View | Anyone |

Check: `GET /api/holders/{token}?wallet=` → `canCreateQuestion`, `canVoteOnQuestion`.  
Briefing: `holderVotes` on `GET /api/agent/briefing?symbol=TMP`.  
Skill: **`HOLDER-VOTES.md`**.

**Agent example (yes/no vote):**
```http
POST /api/communities/{token}/questions
x-wallet-address: 0x…
x-client: agent
Content-Type: application/json

{
  "prompt": "Should we apply for a DexScreener boost this week?",
  "voteType": "yes_no"
}
```

### Tokens & holders

```http
GET /api/tokens/search?q=PEPE
GET /api/holders/{tokenAddress}?wallet=0x…
```

### Reactions

```http
POST /api/posts/{postId}/react
Body: { "tokenAddress": "0x…", "reaction": "👍" | "❤️" | "🔥" }
```

### Cron (platform)

**Work queue (Aeon / worker):**

```http
GET /api/agent/platform-spaces
Authorization: Bearer {CRON_SECRET}
```

Returns opted-in verified spaces, open fundraisers, and funded campaigns ready for skill execution.

**Token sync (Vercel cron):**

```http
POST /api/cron/sync-tokens
Authorization: Bearer {CRON_SECRET}
```

Syncs token launches from `https://api.bankr.bot/token-launches` (hourly on Vercel cron).

---

## Write action requirements

| Action | Who |
|--------|-----|
| Create space | Any connected wallet; token must be Bankr-launched |
| Post / react | Must hold token on Base (on-chain balance > 0) |
| Start holder vote | Verified space admin (`canCreateQuestion`) |
| Cast vote on poll | Token holders only (`canVoteOnQuestion`) |
| Verify | Fee recipient only |

If not holder → reply: "You need to hold $SYMBOL to post" + space link.

---

## Tweet / @bankrbot examples (no skill jargon)

```text
@bankrbot what's the latest on the TMP space?
@bankrbot what's the latest on the TMP community?   ← same intent
@bankrbot how many members in the CTO space?
@bankrbot post in TMP space: gm holders
@bankrbot post this in BNKR space          ← X reply: post parent tweet URL
@bankrbot post hello my words in TMP space ← explicit text, not parent tweet
@bankrbot any fundraisers on the TMP space?
@bankrbot fund $5 to TMP space for Dex profile
@bankrbot start a yes/no vote on TMP: should we do a Dex boost?
@bankrbot vote yes on the TMP space poll
```

**X reply → what to post (`content`):** Skill **`X-REPLY-POST-CONTENT.md`** (v1.7+):
- **"post this/that in $TICKER space"** (replying to a tweet) → parent status URL (shows tweet card on site)
- **`post in TICKER: text`** or **`post {words} in TICKER space`** → user's text only

Bankr platform must load `bankr-communities` skill **before** tool selection (same pattern as TMP fee-rights skill).

---

## Combined with Token Marketplace (TMP)

| Domain | Where |
|--------|--------|
| List, buy, claim fees, launch, petition | [tokenmarketplace.shop/agent.md](https://www.tokenmarketplace.shop/agent.md) + TMP skills |
| Space posts, verify, members, latest | **This guide** + Bankr Space skill |

Example:

```text
@bankrbot claim fees for CTO           → TMP skill
@bankrbot what's new in CTO space  → this site /api/agent/briefing
```

---

## Success reply templates

**Briefing:**

> **$TMP** space — ✓ Verified · **12** members · **34** posts. Latest: "@user shared update…" [View](https://bankr.space/community/0x935e…)

**Post:**

> Posted to **$TMP** holder space. [View thread](https://bankr.space/community/0x935e…)

**Verify:**

> Verified the **$TMP** space as official.

---

## Error codes

| HTTP | Meaning |
|------|---------|
| 401 | Missing `x-wallet-address` |
| 403 | Not holder / not owner |
| 404 | Space not found |
| 409 | Space already exists |
| 503 | Database (KV) not configured |

---

## Install stack (Bankr)

```text
install TMP site agent at https://github.com/anondevv69/bankr-tmp-skill/tree/main/tmp-site-agent
install TMP skills at https://github.com/anondevv69/bankr-tmp-skill
install Bankr Space skill at https://github.com/anondevv69/bankr-space/tree/main/skills/bankr-communities
```

Set `COMMUNITIES_SITE_URL=https://bankr.space` on Bankr.

---

## Source

- GitHub: [github.com/anondevv69/bankr-space](https://github.com/anondevv69/bankr-space)
- Skill pack: `skills/bankr-communities/`
- Web app: `web/`

*When editing, update `web/content/agent.md` then redeploy. Keep in sync with `skills/bankr-communities/agent-guide.md`.*