🔗 Basemate

The discovery layer for XMTP group chats on Base app.

Basemate makes private XMTP groups discoverable. Add Basemate to your group → it gets indexed → users find it through trending, search, and quick actions in Base app.

Two Parts, One Toolkit

This package has two sides:

1. 🏗️ Build — Create & Manage XMTP Groups

Tools for creating and running group chats on Base app. This is the XMTP messaging layer — groups, messages, members, permissions.

2. 📈 Promote — Grow with Basemate Discovery

Tools for making your groups findable. This is the Basemate layer — trending feed, tags, paid boost, paid discovery.

🏗️ Build: XMTP Group Tools

Everything you need to create and manage group chats on Base app.

Setup

# Generate your agent's XMTP wallet
npx basemate init

# Or manually
npm install -g @xmtp/cli
xmtp init --env production

Use production env — groups on dev won't appear in Base app.

📖 Full setup guide →

Create a Group

npx basemate create-group "My Community" "A group for builders" "https://img.com/avatar.png"

This creates an XMTP group, adds Basemate for discovery, and sends an initial message to trigger indexing.

📖 Group creation guide →

Messaging

Agents can send rich content in groups — not just plain text:

| Content Type | Description | |-------------|-------------| | Text | ctx.sendText("hello") | | Markdown | Headers, bold, code blocks, lists | | Replies | Quote-reply to specific messages | | Attachments | Images, files via encrypted remote upload | | Transactions | USDC payment requests (wallet_sendCalls) | | Transaction Refs | Share tx hashes as rich messages | | Reactions | Emoji reactions + thinking indicators | | Inline Actions | Interactive button menus (XIP-67) | | Deeplinks | Group links via Base app UI | | Miniapps | Embedded miniapp frames |

📖 Messaging guide → · Inline actions → · Transactions → · Reactions →

Group Management

| Action | Command | |--------|---------| | Update name | xmtp conversation update-name <id> "New Name" | | Update image | xmtp conversation update-image-url <id> "https://..." | | Add members | xmtp conversation add-members <id> 0xADDRESS | | Remove members | xmtp conversation remove-members <id> 0xADDRESS | | Set permissions | Custom policies per action (add/remove/update) | | Manage admins | Grant/revoke admin and super admin roles |

Max group size: 250 members. Creator is always super admin.

📖 Group management guide →

@Mention Handling

Agents should only respond when @mentioned in groups — silent otherwise. Always respond in DMs.

📖 Mentions guide →

Domain Resolution

Resolve human-readable names to wallet addresses:

• ENS — vitalik.eth → 0xd8dA...
• Basenames — name.base.eth → 0x...
• Farcaster — address → @username

📖 Domain resolution guide →

📈 Promote: Basemate Discovery Tools

Once your group exists, use Basemate to make it discoverable and drive users to it.

How Discovery Works

1. Add Basemate to your group (done automatically by create-group)
2. Send a message to trigger indexing
3. Set tags so users can find your group by interest
4. Your group appears in the Discovery feed in Base app
5. Optional: Boost or unlock paid discovery for higher visibility

Discovery Feed

# See all discoverable groups (ranked: boosted → active → fallback)
npx basemate groups

# See trending communities
npx basemate trending

# Get details on a specific group
npx basemate group-info <groupId>

📖 Discovery guide →

Tags

Tag your group with interests so users and agents can match on topics:

# View tags
npx basemate tags <groupId>

# Set tags
npx basemate tags <groupId> defi,trading,base,nft

Boost ($4.99/week)

Pay for guaranteed visibility in the discovery feed:

• +50 score boost in the trending algorithm
• Top of Discovery feed for 7 days
• is_suggestable: true — agents recommend it, skips 5-member requirement

How: Transfer $4.99 USDC to the treasury on Base → verify with the API.

# After sending USDC tx
npx basemate boost <groupId> <txHash>

📖 Boost guide →

Paid Discovery (Get #1 Trending)

Fully onchain auction on Base. Winner's community gets the top trending slot — maximum visibility.

# Check current auction
npx basemate auction

# Get discovered ($5 USDC, $10 max)
npx basemate discover 5 10 "My Community" "Description"

Features:

• Get discovered — placeBidSimple with USDC approval
• Increase your position — increaseBidSimple to add more USDC
• Pool with your community — contributeToBid lets multiple wallets back one group
• Automatic refunds when outbid
• Rotates at midnight PT — new opportunity every day

📖 Auction guide →

DM Basemate

Agents can message Basemate directly for programmatic interaction:

xmtp send 0xb257b5c180b7b2cb80e35d6079abe68d9cf0467f "Hello Basemate"

📖 DM Basemate guide →

API Reference

Base URL: https://devconnectarg-production.up.railway.app — all public, no auth.

Discovery (Read)

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/groups | Ranked discovery feed | | GET | /api/groups/eligible | All groups with Basemate | | GET | /api/group/:id/tags | Interest tags | | GET | /api/group/:id/boost | Boost status | | GET | /api/group/:id/invite-link | Invite link (read-only) |

Agent Actions (Write)

| Method | Endpoint | Description | |--------|----------|-------------| | PUT | /api/group/:id/tags | Update interest tags | | POST | /api/group/boost/verify-tx | Activate boost with tx proof | | POST | /api/group/add-member | Add wallet address to group |

Onchain (Direct Contract)

| Function | Description | |----------|-------------| | placeBidSimple | Get discovered via auction | | increaseBidSimple | Increase existing bid | | contributeToBid | Pool USDC behind another bid | | getAuctionBids | View all bids | | getFeaturedCommunity | Current auction winner |

📖 Full API reference →

Key Addresses

| What | Address | |------|---------| | Basemate Wallet | 0xb257b5c180b7b2cb80e35d6079abe68d9cf0467f | | Basemate Inbox ID | 91e5c2e39bcc8f553de3db2ce1a9d78f9f2b0bbc6c182653c086892b8048d647 | | Treasury (Boosts) | 0xA189D38cf98A153Cfe83F42B82fcd9c3Cc805Fbe | | Auction Contract | 0xEec2f9560110e7BDBbd7ad7bfBe31d30891D9EFC | | USDC (Base) | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |

Reference Docs

Build (XMTP Groups)

| Doc | What it covers | |-----|----------------| | agent-setup.md | Generate wallet, keys, fund agent | | create-group.md | Create XMTP group + Basemate indexing | | messaging.md | Text, markdown, replies, attachments, deeplinks, miniapps | | inline-actions.md | Interactive button menus (XIP-67) | | transactions.md | In-chat USDC payments | | reactions.md | Emoji reactions, thinking indicators | | group-management.md | Metadata, members, permissions, roles | | mentions.md | Only respond when @mentioned | | domain-resolution.md | ENS, Basenames, Farcaster | | user-consent.md | Spam-free messaging, deployment |

Promote (Basemate Discovery)

| Doc | What it covers | |-----|----------------| | discovery.md | Browse ranked feed, filter by tags | | boost.md | $4.99/week paid discovery | | auction.md | Paid discovery — onchain auction for #1 trending | | dm-basemate.md | Direct message the bot | | api-reference.md | All REST endpoints |

Environment Variables

# Required
XMTP_WALLET_KEY=0x...              # Agent private key
XMTP_DB_ENCRYPTION_KEY=...         # Database encryption
XMTP_ENV=production                # Must be "production" for Base app

# Optional (for CLI scripts)
BASEMATE_AUCTION_CONTRACT=0xEec... # Auction contract
BASEMATE_PRIVATE_KEY=0x...         # For bid/boost scripts
BASEMATE_RPC_URL=https://...       # Base RPC (default: mainnet.base.org)

License

MIT