aibtcdev · whoabuddy · Jan 28, 2026 · Jan 28, 2026 · Jan 28, 2026
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -26,10 +26,9 @@ export default defineConfig({
  { icon: 'x.com', label: 'X', href: 'https://x.com/aibtcdev' },
  ],
  sidebar: [
- {
- label: 'Guides',
- autogenerate: { directory: 'guides' },
- },
+ { label: 'Directory', slug: 'directory' },
+ { label: 'Tokens', slug: 'reference/tokens' },
+ { label: 'Networks', slug: 'reference/networks' },
  { label: 'Glossary', slug: 'glossary' },
  ],
  }),

diff --git a/src/content/docs/directory/index.md b/src/content/docs/directory/index.md
@@ -0,0 +1,53 @@
+---
+title: Directory
+description: Services, tools, and templates in the AIBTC ecosystem.
+---
+
+## AIBTC Services
+
+All AIBTC services follow the same pattern: **mainnet** on `aibtc.com`, **testnet** on `aibtc.dev`.
+
+| Service | Mainnet | Testnet | Source |
+|---------|---------|---------|--------|
+| **x402 API** | [x402.aibtc.com](https://x402.aibtc.com) | [x402.aibtc.dev](https://x402.aibtc.dev) | [GitHub](https://github.com/aibtcdev/x402-api) |
+| **Sponsor Relay** | [x402-relay.aibtc.com](https://x402-relay.aibtc.com) | [x402-relay.aibtc.dev](https://x402-relay.aibtc.dev) | [GitHub](https://github.com/aibtcdev/x402-sponsor-relay) |
+
+**x402 API endpoints:**
+- `/` — Health check
+- `/docs` — OpenAPI documentation
+- `/dashboard` — Usage stats and analytics
+
+**Sponsor Relay endpoints:**
+- `/` — Health check
+- `/docs` — OpenAPI documentation
+
+## Ecosystem Services
+
+| Service | URL | Description |
+|---------|-----|-------------|
+| **STX402** | [stx402.com](https://stx402.com) | x402 endpoint registry ([/docs](https://stx402.com/docs), [/dashboard](https://stx402.com/dashboard)) |
+| **x402 Biwas** | [x402.biwas.xyz](https://x402.biwas.xyz) | AI-powered DeFi analytics ([/analytics](https://x402.biwas.xyz/analytics)) |
+| **StacksScan** | [scan.stacksx402.com](https://scan.stacksx402.com) | x402 ecosystem explorer |
+| **Facilitator** | [facilitator.stacksx402.com/health](https://facilitator.stacksx402.com/health) | Payment verification service |
+
+## Tools & SDKs
+
+| Tool | Description | Links |
+|------|-------------|-------|
+| **@aibtc/mcp-server** | MCP server for Claude Code — Stacks blockchain tools | [npm](https://www.npmjs.com/package/@aibtc/mcp-server) · [GitHub](https://github.com/aibtcdev/aibtc-mcp-server) |
+| **x402-stacks** | TypeScript SDK for x402 payments | [npm](https://www.npmjs.com/package/x402-stacks) · [GitHub](https://github.com/tony1908/x402-stacks-sdk) |
+| **Stacks.js** | Official Stacks JavaScript libraries | [Docs](https://stacks.js.org) · [GitHub](https://github.com/hirosystems/stacks.js) |
+
+## Templates
+
+| Template | Description | Source |
+|----------|-------------|--------|
+| **x402-api** | Cloudflare Workers template for paid endpoints | [GitHub](https://github.com/aibtcdev/x402-api) |
+| **x402-crosschain-example** | Express/Hono with EVM + Stacks | [GitHub](https://github.com/aibtcdev/x402-crosschain-example) |
+
+## More
+
+- **All AIBTC repositories:** [github.com/aibtcdev](https://github.com/aibtcdev)
+- **x402 Protocol spec:** [x402.org](https://x402.org)
+- **Stacks documentation:** [docs.stacks.co](https://docs.stacks.co)
+- **Claude Code:** [claude.ai/code](https://claude.ai/code)
diff --git a/src/content/docs/guides/services.md b/src/content/docs/guides/services.md
diff --git a/src/content/docs/guides/tokens.md b/src/content/docs/guides/tokens.md
diff --git a/src/content/docs/guides/what-is-x402.md b/src/content/docs/guides/what-is-x402.md
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
@@ -1,44 +1,45 @@
 ---
-title: AIBTC Documentation
-description: Documentation for the AIBTC ecosystem - pay-per-use APIs for AI agents.
+title: AIBTC Docs
+description: Reference documentation for the AIBTC x402 ecosystem.
 template: splash
 hero:
- tagline: Pay-per-use APIs for AI agents, powered by Bitcoin.
+ tagline: Reference docs for the x402 ecosystem on Stacks.
  actions:
- - text: Get Started
- link: /guides/what-is-x402/
+ - text: Directory
+ link: /directory/
  icon: right-arrow
- - text: GitHub
- link: https://github.com/aibtcdev
+ - text: Start Building
+ link: https://aibtc.com
  icon: external
  variant: minimal
 ---
 
-import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
-
-AIBTC builds tools that let AI agents pay for the APIs they use, one request at a time. No subscriptions, no API keys, no invoices — just blockchain-verified micropayments.
-
-## What's in the ecosystem
+import { LinkCard, CardGrid } from '@astrojs/starlight/components';
 
 <CardGrid>
-	<Card title="x402 API" icon="rocket">
- Pay-per-use endpoints for AI inference, blockchain data, hashing, and storage. Agents pay with STX, sBTC, or USDCx per request.
-	</Card>
-	<Card title="Sponsor Relay" icon="forward-slash">
- Gasless transactions for AI agents. A sponsor covers network fees so agents can operate without holding STX for gas.
-	</Card>
-	<Card title="StacksScan Explorer" icon="list-format">
- Ecosystem explorer for x402 activity, service stats, and network health across the AIBTC infrastructure.
-	</Card>
-	<Card title="Supported Tokens" icon="random">
- Pay with STX, sBTC, or USDCx. Each token fits a different use case — from general purpose to dollar-stable pricing.
-	</Card>
+	<LinkCard title="Directory" href="/directory/" description="Services, tools, SDKs, and templates." />
+	<LinkCard title="Tokens" href="/reference/tokens/" description="Contract addresses and identifiers." />
+	<LinkCard title="Networks" href="/reference/networks/" description="Endpoints and configurations." />
+	<LinkCard title="Glossary" href="/glossary/" description="Term definitions." />
 </CardGrid>
 
-## Quick Links
+## Quick Reference
 
-<CardGrid>
-	<LinkCard title="What is x402?" href="/guides/what-is-x402/" description="Learn how agents pay for APIs with blockchain micropayments." />
-	<LinkCard title="Services & Tools" href="/guides/services/" description="Explore the APIs, relays, and dashboards in the ecosystem." />
-	<LinkCard title="Supported Tokens" href="/guides/tokens/" description="Compare STX, sBTC, and USDCx and find out where to get them." />
-</CardGrid>
+### Tokens
+
+| Token | Mainnet Contract | Testnet Contract |
+|-------|------------------|------------------|
+| **STX** | Native | Native |
+| **sBTC** | `SM3VDXK3WZZSA84...sbtc-token` | `ST1F7QA2MDF17S8...sbtc-token` |
+| **USDCx** | `SP120SBRBQJ00MC...usdcx` | — |
+
+### Endpoints
+
+| Service | Mainnet | Testnet |
+|---------|---------|---------|
+| **x402 API** | [x402.aibtc.com](https://x402.aibtc.com) | [x402.aibtc.dev](https://x402.aibtc.dev) |
+| **Sponsor Relay** | [x402-relay.aibtc.com](https://x402-relay.aibtc.com) | [x402-relay.aibtc.dev](https://x402-relay.aibtc.dev) |
+
+## Community
+
+- [Weekly Calls](https://www.addevent.com/event/UM20108233) · [Discord](https://discord.gg/5DJaBrf) · [GitHub](https://github.com/aibtcdev) · [X](https://x.com/aibtcdev)
diff --git a/src/content/docs/reference/networks.md b/src/content/docs/reference/networks.md
@@ -0,0 +1,74 @@
+---
+title: Networks
+description: Mainnet and testnet configurations, endpoints, and identifiers.
+---
+
+## Network Overview
+
+| Property | Mainnet | Testnet |
+|----------|---------|---------|
+| **CAIP-2 ID** | `stacks:1` | `stacks:2147483648` |
+| **Chain ID** | `1` | `2147483648` |
+| **Address prefix** | `SP` / `SM` | `ST` / `SN` |
+| **Block time** | ~5 seconds | ~5 seconds |
+| **Bitcoin anchor** | Bitcoin mainnet | Bitcoin testnet |
+
+## AIBTC Endpoints
+
+All AIBTC services: **mainnet** on `aibtc.com`, **testnet** on `aibtc.dev`.
+
+### x402 API
+
+| Endpoint | Mainnet | Testnet |
+|----------|---------|---------|
+| **Base** | `https://x402.aibtc.com` | `https://x402.aibtc.dev` |
+| **Docs** | [/docs](https://x402.aibtc.com/docs) | [/docs](https://x402.aibtc.dev/docs) |
+| **Dashboard** | [/dashboard](https://x402.aibtc.com/dashboard) | [/dashboard](https://x402.aibtc.dev/dashboard) |
+
+### Sponsor Relay
+
+| Endpoint | Mainnet | Testnet |
+|----------|---------|---------|
+| **Base** | `https://x402-relay.aibtc.com` | `https://x402-relay.aibtc.dev` |
+| **Docs** | [/docs](https://x402-relay.aibtc.com/docs) | [/docs](https://x402-relay.aibtc.dev/docs) |
+
+### Facilitator
+
+| Endpoint | URL |
+|----------|-----|
+| **Health** | [facilitator.stacksx402.com/health](https://facilitator.stacksx402.com/health) |
+
+## Ecosystem Endpoints
+
+| Service | Base URL | Additional |
+|---------|----------|------------|
+| **STX402** | [stx402.com](https://stx402.com) | [/docs](https://stx402.com/docs), [/dashboard](https://stx402.com/dashboard) |
+| **x402 Biwas** | [x402.biwas.xyz](https://x402.biwas.xyz) | [/analytics](https://x402.biwas.xyz/analytics) |
+| **StacksScan** | [scan.stacksx402.com](https://scan.stacksx402.com) | — |
+
+## Blockchain APIs
+
+### Hiro API
+
+| Environment | Base URL |
+|-------------|----------|
+| **Mainnet** | `https://api.hiro.so` |
+| **Testnet** | `https://api.testnet.hiro.so` |
+
+**Key endpoints:**
+- `GET /extended/v1/tx/{txid}` — Transaction details
+- `POST /v2/transactions` — Broadcast transactions
+- `GET /extended/v1/address/{principal}/balances` — Token balances
+
+Free API keys at [platform.hiro.so](https://platform.hiro.so). Full docs at [docs.hiro.so](https://docs.hiro.so).
+
+### Block Explorers
+
+| Explorer | Mainnet | Testnet |
+|----------|---------|---------|
+| **Hiro** | [explorer.hiro.so](https://explorer.hiro.so) | [explorer.hiro.so/?chain=testnet](https://explorer.hiro.so/?chain=testnet) |
+
+## Faucets (Testnet)
+
+- **STX** — [explorer.hiro.so/sandbox/faucet](https://explorer.hiro.so/sandbox/faucet?chain=testnet)
+- **sBTC** — [bridge.sbtc.tech](https://bridge.sbtc.tech) (testnet mode)