diff --git a/astro.config.mjs b/astro.config.mjs index a992304..c8482e2 100644 --- 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 new file mode 100644 index 0000000..310cd57 --- /dev/null +++ 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 deleted file mode 100644 index f911849..0000000 --- a/src/content/docs/guides/services.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Services & Tools -description: An overview of every service in the AIBTC x402 ecosystem. -sidebar: - order: 2 ---- - -import { Aside } from '@astrojs/starlight/components'; - -The AIBTC ecosystem is a collection of services that work together to let AI agents pay for API access with blockchain tokens. Here's what's available. - -## AIBTC x402 API - -The main product. A pay-per-use API that gives agents access to AI inference, blockchain lookups, cryptographic hashing, and persistent storage — all payable with STX, sBTC, or USDCx. - -- **Mainnet:** [x402.aibtc.com](https://x402.aibtc.com) -- **Testnet:** [x402.aibtc.dev](https://x402.aibtc.dev) -- **Dashboard:** [dash.aibtc.com](https://dash.aibtc.com) / [dash.aibtc.dev](https://dash.aibtc.dev) - -## Sponsor Relay - -Not every agent holds STX for network fees. The Sponsor Relay covers transaction fees on behalf of agents so they can operate "gasless." The agent still pays for the API call — the relay just picks up the small Stacks network fee. - -- **Mainnet:** [x402-relay.aibtc.com](https://x402-relay.aibtc.com) -- **Testnet:** [x402-relay.aibtc.dev](https://x402-relay.aibtc.dev) - -## STX402 - -An independent x402 registry service that tracks endpoints, pricing, and payment activity across the x402 ecosystem on Stacks. - -- **Live:** [stx402.com](https://stx402.com) -- **Dashboard:** [dash.stx402.com](https://dash.stx402.com) - -## x402 Biwas - -AI-powered analytics for DeFi activity on Stacks. Biwas uses x402 payments to deliver real-time insights and market intelligence. - -- **Live:** [x402.biwas.xyz](https://x402.biwas.xyz) - -## StacksScan Explorer - -An ecosystem explorer that surfaces x402 activity, service stats, and network health across the AIBTC infrastructure. - -- **Live:** [scan.stacksx402.com](https://scan.stacksx402.com) - -## Facilitator - -The behind-the-scenes payment verification service. When an agent sends a signed payment, the facilitator confirms the transaction is valid before the API releases the response. You won't interact with it directly — it just makes everything work. - -- **Live:** [facilitator.stacksx402.com](https://facilitator.stacksx402.com) - -## Quick reference - -| Service | Live URL | Dashboard | -|---------|----------|-----------| -| x402 API | [x402.aibtc.com](https://x402.aibtc.com) | [dash.aibtc.com](https://dash.aibtc.com) | -| Sponsor Relay | [x402-relay.aibtc.com](https://x402-relay.aibtc.com) | — | -| STX402 | [stx402.com](https://stx402.com) | [dash.stx402.com](https://dash.stx402.com) | -| x402 Biwas | [x402.biwas.xyz](https://x402.biwas.xyz) | — | -| StacksScan | [scan.stacksx402.com](https://scan.stacksx402.com) | — | -| Facilitator | [facilitator.stacksx402.com](https://facilitator.stacksx402.com) | — | - - diff --git a/src/content/docs/guides/tokens.md b/src/content/docs/guides/tokens.md deleted file mode 100644 index 6a6b5b8..0000000 --- a/src/content/docs/guides/tokens.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Supported Tokens -description: The tokens you can use to pay for x402 API requests on Stacks. -sidebar: - order: 3 ---- - -import { Aside } from '@astrojs/starlight/components'; - -x402 on Stacks accepts three tokens for payment. Each has different strengths depending on your use case. - -## STX - -The native token of the [Stacks](https://www.stacks.co/) blockchain. Every Stacks transaction uses STX for network fees, and it's the most widely available token in the ecosystem. Available on both mainnet and testnet. - -## sBTC - -Bitcoin on Stacks, backed 1:1 by real BTC. If you want to pay with Bitcoin value without leaving the Stacks network, sBTC is the way to do it. Available on both mainnet and testnet. - -## USDCx - -A bridged US dollar stablecoin on Stacks. Because its value is pegged to USD, your API costs stay predictable regardless of crypto market movement. Currently available on mainnet only. - -## Where to get tokens - -- **STX** — Available on major exchanges. Transfer to a Stacks-compatible wallet. -- **sBTC** — Bridge BTC to Stacks using the [sBTC bridge](https://bridge.sbtc.tech/). -- **USDCx** — Bridge USDC to Stacks from supported networks. -- **Testnet tokens** — Get free test STX and sBTC from the [Stacks testnet faucet](https://explorer.hiro.so/sandbox/faucet?chain=testnet). - -## Which token should I use? - -| Token | Best for | Networks | -|-------|----------|----------| -| **STX** | General use, lowest friction | Mainnet, Testnet | -| **sBTC** | Paying with Bitcoin value | Mainnet, Testnet | -| **USDCx** | Predictable dollar-denominated costs | Mainnet only | - - diff --git a/src/content/docs/guides/what-is-x402.md b/src/content/docs/guides/what-is-x402.md deleted file mode 100644 index 1958f7b..0000000 --- a/src/content/docs/guides/what-is-x402.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: What is x402? -description: A quick introduction to x402 — the pay-per-request protocol for AI agents. -sidebar: - order: 1 ---- - -import { LinkCard } from '@astrojs/starlight/components'; - -## The problem - -AI agents need access to APIs — for inference, blockchain data, storage, and more. Traditional billing (API keys, monthly invoices, subscriptions) doesn't work well when autonomous agents are making thousands of small requests across many services. There's no human around to manage accounts or approve charges. - -## How x402 works - -The [x402 protocol](https://www.x402.org/) turns every API call into a simple payment flow: - -1. An agent sends a request to a protected API endpoint. -2. The server replies with HTTP status **402 Payment Required**, along with the price and accepted tokens. -3. The agent signs a blockchain transaction for the exact amount. -4. The agent resends the original request with the signed payment attached as a header. -5. The server verifies the payment and returns the data. - -No API keys. No accounts. No invoices. The agent pays exactly what it uses, one request at a time. - -## Why Stacks? - -AIBTC builds on [Stacks](https://www.stacks.co/), a Bitcoin Layer 2 with smart contracts and fast block times. Stacks settles to Bitcoin, giving you the security of the Bitcoin network while supporting the programmable payments x402 requires. That means agents can pay with Bitcoin-backed assets in near real-time. - -## What you can pay with - -x402 on Stacks supports three tokens: - -- **STX** — The native Stacks token. Used for transaction fees and API payments. -- **sBTC** — Bitcoin on Stacks, backed 1:1 by BTC. Pay with real Bitcoin value. -- **USDCx** — A US dollar stablecoin on Stacks. Predictable, dollar-denominated costs. - -Learn more on the [Supported Tokens](/guides/tokens/) page. - -## Next steps - - - diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 18d8917..3a92096 100644 --- 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'; - - Pay-per-use endpoints for AI inference, blockchain data, hashing, and storage. Agents pay with STX, sBTC, or USDCx per request. - - - Gasless transactions for AI agents. A sponsor covers network fees so agents can operate without holding STX for gas. - - - Ecosystem explorer for x402 activity, service stats, and network health across the AIBTC infrastructure. - - - Pay with STX, sBTC, or USDCx. Each token fits a different use case — from general purpose to dollar-stable pricing. - + + + + -## Quick Links +## Quick Reference - - - - - +### 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 new file mode 100644 index 0000000..923fa69 --- /dev/null +++ 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) diff --git a/src/content/docs/reference/tokens.md b/src/content/docs/reference/tokens.md new file mode 100644 index 0000000..b855331 --- /dev/null +++ b/src/content/docs/reference/tokens.md @@ -0,0 +1,74 @@ +--- +title: Tokens +description: Contract addresses and identifiers for x402 payment tokens. +--- + +## Supported Tokens + +| Token | Type | Decimals | Mainnet | Testnet | +|-------|------|----------|---------|---------| +| **STX** | Native | 6 | Yes | Yes | +| **sBTC** | SIP-010 | 8 | Yes | Yes | +| **USDCx** | SIP-010 | 6 | Yes | No | + +## Contract Addresses + +### STX + +Native token — no contract address. + +### sBTC + +Bitcoin on Stacks, backed 1:1 by BTC. + +| Network | Contract ID | +|---------|-------------| +| **Mainnet** | `SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token` | +| **Testnet** | `ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-token` | + +Asset identifier: `::sbtc-token` + +### USDCx + +Bridged USDC via [Circle Xreserve](https://www.circle.com/xreserve) on Stacks. + +| Network | Contract ID | +|---------|-------------| +| **Mainnet** | `SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx` | +| **Testnet** | Not deployed | + +Asset identifier: `::usdcx-token` + +**Bridging:** See [Stacks bridging documentation](https://docs.stacks.co/guides/bridge-assets-to-stacks) for how to bridge USDC to Stacks. + +## CAIP-19 Asset Identifiers + +[CAIP-19](https://chainagnostic.org/CAIPs/caip-19) provides chain-agnostic asset identification. See [our CAIP-19 PR for Stacks](https://github.com/ChainAgnostic/namespaces/pull/167) for the full specification. + +| Token | Mainnet | Testnet | +|-------|---------|---------| +| **STX** | `stacks:1/slip44:5757` | `stacks:2147483648/slip44:5757` | +| **sBTC** | `stacks:1/sip010:SM3VDX...::sbtc-token` | `stacks:2147483648/sip010:ST1F7Q...::sbtc-token` | +| **USDCx** | `stacks:1/sip010:SP120S...::usdcx-token` | — | + +## Where to Get Tokens + +### Mainnet + +- **STX** — Major exchanges (Coinbase, Binance, OKX). Transfer to a Stacks wallet. +- **sBTC** — Bridge BTC at [bridge.sbtc.tech](https://bridge.sbtc.tech) +- **USDCx** — Bridge USDC via [supported bridges](https://docs.stacks.co/guides/bridge-assets-to-stacks) + +### Testnet + +- **STX** — [Stacks Testnet Faucet](https://explorer.hiro.so/sandbox/faucet?chain=testnet) +- **sBTC** — [sBTC Testnet Faucet](https://bridge.sbtc.tech) (testnet mode) + +## Token Standard + +All fungible tokens follow [SIP-010](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md): + +- `transfer` — Move tokens between addresses +- `get-balance` — Check balance for an address +- `get-total-supply` — Total circulating supply +- `get-name` / `get-symbol` / `get-decimals` — Token metadata