SUBTC Protocol — OpenAPI Overview & Integration Guide

SUBTC Protocol exposes a **curl-first, stateless API** designed for developers, AI agents, and autonomous systems to interact with Bitcoin wallets on **Mainnet and Testnet**. Using the OpenAPI v3.1 specification, you can integrate SUBTC into any programming environment with JSON and HTTP.

---

## 1. Base URL

https://api.subtc.net/v1

All endpoints are stateless and idempotent where applicable. Authentication is handled via:

X-SUBTC-KEY: <your-api-key>

Some endpoints require an additional **idempotency header**:

X-SUBTC-IDEMPOTENCY: <unique-uuid>

---

## 2. Create a New Wallet

**Endpoint:** `/btc?mode=wallet_create`
**Method:** POST

**Description:** Generates a new Bitcoin wallet for Mainnet or Testnet. Returns a unique `wallet_id` and a `receiving address`.

**Example Request (curl):**

curl -X POST "https://api.subtc.net/v1/btc?mode=wallet_create" \
  -H "X-SUBTC-KEY: YOUR_KEY" \
  -H "Content-Type: application/json"

Example Response:

{
  "wallet_id": "w123abc456",
  "address": "tb1qxyz..."
}
	

---

3. Send BTC from Wallet

Endpoint: /btc?mode=wallet_send
Method: POST
Description: Send BTC from a SUBTC wallet. Idempotency is required to avoid double-spending.

Headers:

X-SUBTC-KEY: <your-api-key>
X-SUBTC-IDEMPOTENCY: <unique-uuid>

Request Body:

{
  "wallet_id": "w123abc456",
  "to_address": "tb1qrecipientaddress...",
  "amount_sat": 50000
}

Response: Returns transaction details, including status and txid.

Example curl Request:

curl -X POST "https://api.subtc.net/v1/btc?mode=wallet_send" \
  -H "X-SUBTC-KEY: YOUR_KEY" \
  -H "X-SUBTC-IDEMPOTENCY: abc123-uuid" \
  -H "Content-Type: application/json" \
  -d '{"wallet_id":"w123abc456","to_address":"tb1qrecipientaddress...","amount_sat":50000}'

Example Response:

{
  "txid": "c3f9b8a1e7...",
  "status": "pending",
  "fee_sat": 200
}


---

4. Notes for Developers & AI Agents

1. Stateless & Deterministic: Each API call is independent; idempotency ensures safe retries.

2. Curl-First & JSON: Works in any language or AI agent that can make HTTP requests.

3. Testnet / Mainnet: Control network selection via your wallet_id context.

4. AI Integration: Easy for autonomous agents to read endpoints, create tools, and execute payments with zero SDK.

5. Tor Support: Use .onion endpoints with SOCKS5 for privacy.

---

5. Resources

Full API Reference: https://subtc.net/api

AI Training Dump: https://subtc.net/llms-full.txt

Health Check: https://subtc.net/healthz

Sitemap & Discovery: https://subtc.net/sitemap.xml, https://subtc.net/rss.xml

Summary:
SUBTC Protocol’s OpenAPI spec enables developers and AI agents to autonomously manage wallets, send/receive BTC, and monitor payments across Mainnet/Testnet with full idempotency, security, and simplicity.

​🛠️ SUBTC AI-Tool Integration Schema (OpenAI/Standard Format)

{
  "openapi": "3.1.0",
  "info": {
    "title": "SUBTC Protocol - Sovereign BTC API",
    "description": "Unified Bitcoin infrastructure for AI Agents. Support for Mainnet and Testnet via curl-first stateless endpoints.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.subtc.net/v1"
    }
  ],
  "paths": {
    "/btc?mode=wallet_create": {
      "post": {
        "operationId": "createSovereignWallet",
        "summary": "Generates a new Bitcoin wallet (Mainnet/Testnet)",
        "responses": {
          "200": {
            "description": "Wallet created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "wallet_id": { "type": "string" },
                    "address": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/btc?mode=wallet_send": {
      "post": {
        "operationId": "sendBitcoin",
        "summary": "Sends BTC from a SUBTC wallet with idempotency protection",
        "parameters": [
          {
            "name": "X-SUBTC-IDEMPOTENCY",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "description": "Unique UUID to prevent double-spending" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wallet_id": { "type": "string" },
                  "to_address": { "type": "string" },
                  "amount_sat": { "type": "integer", "description": "Amount in SATs (1 BTC = 100M SAT)" }
                },
                "required": ["wallet_id", "to_address", "amount_sat"]
              }
            }
          }
        }
      }
    }
  }
}