{
  "openapi": "3.1.0",
  "info": {
    "title": "Paybyte PBE HTTP API",
    "version": "0.0.1",
    "description": "PBE Mainnet public RPC and PBE-PAY Commerce API. networkId=1, chainId=PBE-MAINNET, protocol=1.0. Commerce settlement uses canonical-chain confirmation depth; hardFinality=false. PBE 0.0.1 is an experimental mainnet release and does not provide hard/deep-reorg finality."
  },
  "servers": [
    {
      "url": "https://paybyte.org",
      "description": "Paybyte public primary node"
    }
  ],
  "components": {
    "securitySchemes": {
      "merchantBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "commerce.webhooks.manageToken on the merchant-controlled PBE node"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "const": false
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "ok",
          "error"
        ]
      },
      "PaymentRequestInput": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "string",
            "pattern": "^pbe1"
          },
          "amount": {
            "type": "string"
          },
          "amountBaseUnits": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "reference": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9._:-]+$"
          },
          "label": {
            "type": "string",
            "maxLength": 80
          },
          "confirmations": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          }
        },
        "required": [
          "recipient"
        ]
      },
      "SignedTransaction": {
        "type": "object",
        "properties": {
          "version": {
            "const": 2
          },
          "networkId": {
            "const": 1
          },
          "type": {
            "const": 1
          },
          "senderPublicKey": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{64}$"
          },
          "senderAddress": {
            "type": "string",
            "pattern": "^pbe1"
          },
          "nonce": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "fee": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "timestamp": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "payload": {
            "type": "object",
            "properties": {
              "recipient": {
                "type": "string",
                "pattern": "^pbe1"
              },
              "amount": {
                "type": "string",
                "pattern": "^[0-9]+$"
              },
              "paymentReference": {
                "type": "string",
                "maxLength": 64
              }
            },
            "required": [
              "recipient",
              "amount"
            ]
          },
          "signature": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]{128}$"
          }
        },
        "required": [
          "version",
          "networkId",
          "type",
          "senderPublicKey",
          "senderAddress",
          "nonce",
          "fee",
          "timestamp",
          "payload",
          "signature"
        ]
      },
      "WebhookInput": {
        "type": "object",
        "properties": {
          "recipient": {
            "type": "string",
            "pattern": "^pbe1"
          },
          "amount": {
            "type": "string"
          },
          "amountBaseUnits": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "reference": {
            "type": "string",
            "maxLength": 64
          },
          "confirmations": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000
          },
          "callbackUrl": {
            "type": "string",
            "format": "uri"
          },
          "ttlSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 604800
          }
        },
        "required": [
          "recipient",
          "reference",
          "callbackUrl"
        ]
      },
      "NodeStatus": {
        "type": "object",
        "properties": {
          "softwareVersion": {
            "const": "0.0.1"
          },
          "protocolVersion": {
            "const": "1.0"
          },
          "networkId": {
            "const": 1
          },
          "chainId": {
            "const": "PBE-MAINNET"
          },
          "genesisHash": {
            "type": "string",
            "const": "75d92b8389173d388e9989b208b8f623e0e88f9059f02e66b73cfbf4c412e5eb"
          },
          "height": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "slot": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "hash": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "stateRoot": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "consensusRoot": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "nodeId": {
            "type": "string",
            "pattern": "^pbenode_[0-9a-f]{32}$"
          },
          "endpoint": {
            "type": "string"
          },
          "knownPeerCount": {
            "type": "integer",
            "minimum": 0
          },
          "bestKnownPeerHeight": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "syncLagBlocks": {
            "type": "string",
            "pattern": "^[0-9]+$"
          },
          "syncState": {
            "type": "string",
            "enum": [
              "synced",
              "catching-up"
            ]
          },
          "time": {
            "type": "string",
            "pattern": "^[0-9]+$"
          }
        },
        "required": [
          "softwareVersion",
          "protocolVersion",
          "networkId",
          "chainId",
          "genesisHash",
          "height",
          "slot",
          "hash",
          "nodeId",
          "syncState",
          "time"
        ]
      }
    }
  },
  "paths": {
    "/rpc/status": {
      "get": {
        "summary": "Node status",
        "description": "Public chain, synchronization and peer-discovery status. Includes the frozen mainnet genesis hash used for chain-identity verification. Hosted output excludes operator-wallet details.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "status": {
                      "$ref": "#/components/schemas/NodeStatus"
                    }
                  },
                  "required": [
                    "ok",
                    "status"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/rpc/consensus": {
      "get": {
        "summary": "Consensus parameters",
        "description": "Hybrid participation parameters and holding multiplier schedule.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/rpc/block/{height}": {
      "get": {
        "summary": "Block by height",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "height",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ]
      }
    },
    "/rpc/balance/{address}": {
      "get": {
        "summary": "Account balance and nonce",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/rpc/address/{address}/transactions": {
      "get": {
        "summary": "Address transactions",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          }
        ]
      }
    },
    "/rpc/transaction/{txid}": {
      "get": {
        "summary": "Transaction by TXID",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "txid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-fA-F]{64}$"
            }
          }
        ]
      }
    },
    "/rpc/broadcast": {
      "post": {
        "summary": "Broadcast signed transaction",
        "description": "Submits a locally signed transfer transaction v2.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transaction": {
                    "$ref": "#/components/schemas/SignedTransaction"
                  }
                },
                "required": [
                  "transaction"
                ]
              }
            }
          }
        }
      }
    },
    "/rpc/commerce/catalog": {
      "get": {
        "summary": "Commerce endpoint catalog",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/rpc/commerce/info": {
      "get": {
        "summary": "Commerce capabilities",
        "description": "Includes default/high-value confirmation guidance and hardFinality=false.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/rpc/commerce/payment-request": {
      "post": {
        "summary": "Create PBE-PAY request",
        "description": "Stateless request generation. Requires exactly one of amount or amountBaseUnits.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequestInput"
              }
            }
          }
        }
      }
    },
    "/rpc/commerce/payment/{reference}": {
      "get": {
        "summary": "Verify exact PBE-PAY payment",
        "description": "Matches signed reference + expected recipient + exact amount.",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "recipient",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "amountBaseUnits",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "confirmations",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 12
            }
          }
        ]
      }
    },
    "/rpc/commerce/webhooks": {
      "post": {
        "summary": "Register merchant webhook",
        "description": "Optional node feature; disabled by default.",
        "responses": {
          "201": {
            "description": "Subscription created"
          },
          "401": {
            "description": "Invalid bearer token"
          },
          "503": {
            "description": "Webhooks disabled or not configured"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookInput"
              }
            }
          }
        },
        "security": [
          {
            "merchantBearer": []
          }
        ]
      }
    },
    "/rpc/commerce/webhooks/{id}": {
      "get": {
        "summary": "Inspect merchant webhook",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^pbewh_[a-f0-9]{32}$"
            }
          }
        ],
        "security": [
          {
            "merchantBearer": []
          }
        ]
      }
    },
    "/rpc/commerce/webhooks/{id}/cancel": {
      "post": {
        "summary": "Cancel merchant webhook",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^pbewh_[a-f0-9]{32}$"
            }
          }
        ],
        "security": [
          {
            "merchantBearer": []
          }
        ]
      }
    },
    "/p2p/status": {
      "get": {
        "summary": "P2P node status",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/p2p/hello": {
      "post": {
        "summary": "Signed peer handshake",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "hello": {
                    "type": "object",
                    "properties": {
                      "softwareVersion": {
                        "type": "string",
                        "example": "0.0.1"
                      },
                      "protocolVersion": {
                        "type": "string",
                        "example": "1.0"
                      },
                      "networkId": {
                        "type": "integer",
                        "const": 1
                      },
                      "chainId": {
                        "type": "string",
                        "const": "PBE-MAINNET"
                      },
                      "genesisHash": {
                        "type": "string",
                        "pattern": "^[0-9a-f]{64}$",
                        "example": "75d92b8389173d388e9989b208b8f623e0e88f9059f02e66b73cfbf4c412e5eb"
                      },
                      "nodeId": {
                        "type": "string",
                        "pattern": "^pbenode_[0-9a-f]{32}$"
                      },
                      "nodePublicKey": {
                        "type": "string",
                        "pattern": "^[0-9a-f]{64}$"
                      },
                      "height": {
                        "type": "string",
                        "pattern": "^(0|[1-9][0-9]*)$"
                      },
                      "hash": {
                        "type": "string",
                        "pattern": "^[0-9a-f]{64}$"
                      },
                      "timestamp": {
                        "type": "string",
                        "pattern": "^(0|[1-9][0-9]*)$"
                      },
                      "endpoint": {
                        "type": "string"
                      },
                      "signature": {
                        "type": "string",
                        "pattern": "^[0-9a-f]{128}$"
                      }
                    },
                    "required": [
                      "softwareVersion",
                      "protocolVersion",
                      "networkId",
                      "chainId",
                      "genesisHash",
                      "nodeId",
                      "nodePublicKey",
                      "height",
                      "hash",
                      "timestamp",
                      "endpoint",
                      "signature"
                    ],
                    "additionalProperties": false
                  }
                }
              }
            }
          }
        }
      }
    },
    "/p2p/transaction": {
      "post": {
        "summary": "Peer transaction relay",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "transaction": {
                    "$ref": "#/components/schemas/SignedTransaction"
                  }
                },
                "required": [
                  "transaction"
                ]
              }
            }
          }
        }
      }
    },
    "/p2p/block": {
      "post": {
        "summary": "Peer block relay",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "block": {
                    "type": "object"
                  }
                },
                "required": [
                  "block"
                ]
              }
            }
          }
        }
      }
    },
    "/p2p/blocks": {
      "get": {
        "summary": "Canonical block batch",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 16,
              "default": 16
            }
          }
        ]
      }
    },
    "/p2p/peers": {
      "get": {
        "summary": "Verified peer hints",
        "description": "",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ]
      }
    }
  }
}