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<br>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..."
}
	

---

1. Send BTC from Wallet

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

Headers:

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

Request Body:<br>

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

<br>Response: Returns transaction details, including status and txid.

Example curl Request:<br>

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
}


---

1. Notes for Developers & AI Agents

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

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

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

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

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

---

1. 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:<br>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)<br>

{
  "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"]
              }
            }
          }
        }
      }
    }
  }
}