{
  "openapi": "3.1.0",
  "info": {
    "title": "Prove It Onchain — Agent API",
    "version": "1.0.0",
    "summary": "Let AI agents create Counterparty proofs on Bitcoin with their own wallet.",
    "description": "Non-custodial, Bitcoin-native, bring-your-own-wallet. POST a claim (and optionally a file or its SHA-256) with your agent's Bitcoin address. The server stores a public claim record, then returns an UNSIGNED transaction (PSBT) that issues a one-of-one Counterparty token whose description is the record URL, with the service fee already included as one extra output. You sign with your own key and POST it back (or broadcast it yourself). We never see your keys. Inscribe and Vanity Names via the API are coming soon.\n\nBroadcast through /api/v1/broadcast is open to any address (rate-limited per IP); agents can also broadcast the signed transaction themselves through any Bitcoin node or mempool.space.",
    "contact": {
      "url": "https://proveitonchain.com/api"
    }
  },
  "servers": [
    {
      "url": "https://proveitonchain.com"
    }
  ],
  "externalDocs": {
    "url": "https://proveitonchain.com/api",
    "description": "Human docs with curl and JS signing examples"
  },
  "tags": [
    {
      "name": "proofs"
    },
    {
      "name": "pricing"
    }
  ],
  "paths": {
    "/api/v1/quote": {
      "get": {
        "operationId": "getQuote",
        "tags": [
          "pricing"
        ],
        "summary": "Current fees",
        "description": "Pricing for every product is a flat USD service fee plus the Bitcoin network fee on top. Proof: $2 + network fee (the $2 is paid to the service address inside the mint transaction). Also returns current network fee rates and the coming-soon products: Inscribe ($5 + network fee) and Vanity Names ($21 + network fee).",
        "parameters": [
          {
            "name": "network",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "mainnet",
                "testnet4",
                "signet"
              ],
              "default": "mainnet"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Fees temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/proofs": {
      "post": {
        "operationId": "createProof",
        "tags": [
          "proofs"
        ],
        "summary": "Create a proof and get an unsigned transaction",
        "description": "Hashes the file (or takes your sha256), stores the claim record at /t/{record_id}.json exactly like the website, pins the service fee, and composes the Counterparty issuance: numeric asset (or a named asset you own), quantity 1, indivisible, locked supply, description = record URL, plus the fee output. Returns the unsigned PSBT. Expires after 30 minutes.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateProof"
              },
              "examples": {
                "text": {
                  "value": {
                    "claim": "I wrote this first",
                    "address": "bc1q..."
                  }
                },
                "file": {
                  "value": {
                    "claim": "Original artwork",
                    "file": {
                      "base64": "iVBORw0...",
                      "name": "art.png",
                      "type": "image/png"
                    },
                    "address": "bc1q..."
                  }
                },
                "hash": {
                  "value": {
                    "claim": "I hold this contract",
                    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
                    "file_name": "contract.pdf",
                    "address": "bc1q..."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Unsigned proof transaction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProofCreated"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Too large",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream (Counterparty / mempool.space) failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Fees temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/broadcast": {
      "post": {
        "operationId": "broadcastProof",
        "tags": [
          "proofs"
        ],
        "summary": "Broadcast the signed proof transaction",
        "description": "Send the signed PSBT (base64 or hex; finalized or not) or the signed raw tx hex. The server checks it is exactly the transaction it composed (same inputs and outputs) and that it pays the exact pinned service fee, then relays it via mempool.space. Idempotent. Open to any address; rate-limited per IP (see GET /api/v1/quote → broadcast_public).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Broadcast"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Broadcast",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Broadcasted"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream (Counterparty / mempool.space) failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/proofs/{record_id}": {
      "get": {
        "operationId": "getProof",
        "tags": [
          "proofs"
        ],
        "summary": "Proof status",
        "parameters": [
          {
            "name": "record_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{8,64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProofStatus"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable reason."
          },
          "code": {
            "type": "string",
            "description": "Stable machine code, e.g. bad_address, claim_required, rate_limited, broadcast_not_enabled, tx_mismatch, expired."
          },
          "status": {
            "type": "integer"
          }
        }
      },
      "Fee": {
        "type": "object",
        "properties": {
          "usd": {
            "type": "number"
          },
          "sats": {
            "type": [
              "integer",
              "null"
            ]
          },
          "address": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Quote": {
        "type": "object",
        "properties": {
          "api_version": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "btc_usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "proof": {
            "type": "object",
            "properties": {
              "service_fee": {
                "$ref": "#/components/schemas/Fee"
              },
              "network_fee_estimate": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "pricing": {
                "type": "string",
                "example": "$2 + network fee"
              }
            }
          },
          "network_fee_rates": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "economy": {
                "type": "integer"
              },
              "standard": {
                "type": "integer"
              },
              "fast": {
                "type": "integer"
              },
              "floor": {
                "type": "integer"
              }
            }
          },
          "coming_soon": {
            "type": "object",
            "properties": {
              "inscribe": {
                "type": "object",
                "properties": {
                  "pricing": {
                    "type": "string",
                    "example": "$5 + network fee"
                  },
                  "service_fee": {
                    "type": "object"
                  },
                  "available_via_api": {
                    "type": "boolean"
                  }
                }
              },
              "vanity_name": {
                "type": "object",
                "description": "$21 service fee + network fee (Bitcoin miner fees for registering and delivering the name). Orders add a 1–999 sat tag.",
                "properties": {
                  "pricing": {
                    "type": "string",
                    "example": "$21 + network fee"
                  },
                  "service_fee": {
                    "type": "object",
                    "properties": {
                      "usd": {
                        "type": "number"
                      },
                      "sats": {
                        "type": [
                          "integer",
                          "null"
                        ]
                      }
                    }
                  },
                  "total": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "usd": {
                        "type": "number"
                      },
                      "sats": {
                        "type": "integer"
                      }
                    }
                  },
                  "available_via_api": {
                    "type": "boolean"
                  },
                  "network_fee": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "properties": {
                      "usd": {
                        "type": "number"
                      },
                      "sats": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          },
          "expires_in_seconds": {
            "type": "integer"
          },
          "broadcast_public": {
            "type": "boolean"
          }
        }
      },
      "CreateProof": {
        "type": "object",
        "required": [
          "claim",
          "address"
        ],
        "properties": {
          "claim": {
            "type": "string",
            "maxLength": 200,
            "description": "One line: what you are proving."
          },
          "details": {
            "type": "string",
            "maxLength": 2000
          },
          "title": {
            "type": "string",
            "maxLength": 140
          },
          "address": {
            "type": "string",
            "description": "Your agent's Bitcoin address. It funds, signs, and receives the token. P2WPKH (bc1q…) recommended."
          },
          "file": {
            "description": "File bytes as base64 / data: URL, an https URL, or an object.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "base64": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "name": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "file_url": {
            "type": "string",
            "format": "uri",
            "description": "https URL the server downloads and hashes (max 6 MB)."
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{64}$",
            "description": "Prove a file without sending it. If you also send the file, it must match."
          },
          "file_name": {
            "type": "string"
          },
          "file_type": {
            "type": "string"
          },
          "file_size": {
            "type": "integer"
          },
          "name": {
            "type": "string",
            "description": "Optional named asset (or subasset) your address already owns. Omit for a free numeric asset."
          },
          "fee_rate": {
            "type": "integer",
            "minimum": 5,
            "description": "sat/vB. Default: mempool.space half-hour rate, floor 5."
          },
          "allow_unconfirmed_inputs": {
            "type": "boolean",
            "default": false
          },
          "network": {
            "type": "string",
            "enum": [
              "mainnet",
              "testnet4",
              "signet"
            ],
            "default": "mainnet"
          }
        }
      },
      "ProofCreated": {
        "type": "object",
        "properties": {
          "record_id": {
            "type": "string"
          },
          "record_url": {
            "type": "string",
            "format": "uri"
          },
          "verify_url": {
            "type": "string",
            "format": "uri"
          },
          "asset": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "claim": {
            "type": "string"
          },
          "sha256": {
            "type": "string"
          },
          "proof": {
            "type": "string",
            "enum": [
              "text",
              "file"
            ]
          },
          "unsigned_psbt": {
            "type": "string",
            "description": "Base64 PSBT with witnessUtxo on every input."
          },
          "unsigned_psbt_hex": {
            "type": "string"
          },
          "unsigned_tx_hex": {
            "type": "string"
          },
          "sign": {
            "type": "object",
            "properties": {
              "address": {
                "type": "string"
              },
              "inputs": {
                "type": "array",
                "items": {
                  "type": "integer"
                }
              },
              "sighash": {
                "type": "string"
              }
            }
          },
          "fees": {
            "type": "object",
            "properties": {
              "service": {
                "$ref": "#/components/schemas/Fee"
              },
              "network": {
                "type": "object",
                "properties": {
                  "sats": {
                    "type": "integer"
                  },
                  "sat_per_vbyte": {
                    "type": "integer"
                  },
                  "vsize": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  }
                }
              },
              "total_sats": {
                "type": "integer"
              }
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "next": {
            "type": "object"
          }
        }
      },
      "Broadcast": {
        "type": "object",
        "required": [
          "record_id"
        ],
        "properties": {
          "record_id": {
            "type": "string"
          },
          "signed_psbt": {
            "type": "string",
            "description": "base64 or hex"
          },
          "signed_tx_hex": {
            "type": "string"
          }
        }
      },
      "Broadcasted": {
        "type": "object",
        "properties": {
          "record_id": {
            "type": "string"
          },
          "txid": {
            "type": "string"
          },
          "asset": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "already_broadcast": {
            "type": "boolean"
          },
          "verify_url": {
            "type": "string"
          },
          "record_url": {
            "type": "string"
          },
          "explorer_url": {
            "type": "string"
          }
        }
      },
      "ProofStatus": {
        "type": "object",
        "properties": {
          "record_id": {
            "type": "string"
          },
          "record_url": {
            "type": "string"
          },
          "asset": {
            "type": [
              "string",
              "null"
            ]
          },
          "network": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_signature",
              "expired",
              "pending",
              "confirmed",
              "not_found_in_mempool",
              "unknown"
            ]
          },
          "txid": {
            "type": [
              "string",
              "null"
            ]
          },
          "confirmations": {
            "type": [
              "integer",
              "null"
            ]
          },
          "block_height": {
            "type": [
              "integer",
              "null"
            ]
          },
          "verify_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "explorer_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "inscription_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "via": {
            "type": "string"
          }
        }
      }
    }
  }
}
