{
  "openapi": "3.1.0",
  "info": {
    "title": "Quub Exchange - Chain Service",
    "version": "2.0.0",
    "description": "Wallet management, on-chain transaction registry, and blockchain adapter lifecycle\nfor supported Layer 1 and Layer 2 networks. Supports both institutional and retail\nwallets, on-chain custody, and cross-chain monitoring.\n",
    "license": {
      "name": "Proprietary",
      "identifier": "Proprietary"
    },
    "x-maturity": "stable",
    "x-service-tier": "core"
  },
  "servers": [
    {
      "url": "https://api.quub.exchange/v2",
      "description": "Production API"
    },
    {
      "url": "https://api.sandbox.quub.exchange/v2",
      "description": "Sandbox API"
    }
  ],
  "tags": [
    {
      "name": "Chains",
      "description": "Manage blockchain network definitions (system-wide reference data)."
    },
    {
      "name": "Wallets",
      "description": "Manage user and organization-linked blockchain wallets."
    },
    {
      "name": "OnChainTxs",
      "description": "Track on-chain transactions across supported chains."
    },
    {
      "name": "ChainAdapters",
      "description": "Manage blockchain network connectors and RPC configurations."
    }
  ],
  "paths": {
    "/chains": {
      "get": {
        "tags": [
          "Chains"
        ],
        "summary": "List blockchain networks",
        "operationId": "listChains",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "networkType",
            "in": "query",
            "description": "Filter by network type",
            "schema": {
              "type": "string",
              "enum": [
                "MAINNET",
                "TESTNET",
                "DEVNET"
              ]
            }
          },
          {
            "name": "layer",
            "in": "query",
            "description": "Filter by chain layer",
            "schema": {
              "type": "string",
              "enum": [
                "L1",
                "L2"
              ]
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by status",
            "schema": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "DEPRECATED",
                "DISABLED"
              ]
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "List of blockchain networks",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Chain"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Chains"
        ],
        "summary": "Register a new blockchain network",
        "operationId": "createChain",
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateChainInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "201": {
            "description": "Chain created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Chain"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "traceId": {
                          "type": "string",
                          "description": "Distributed tracing identifier",
                          "example": "trace-550e8400-e29b-41d4-a716"
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/chains/{chainId}": {
      "get": {
        "tags": [
          "Chains"
        ],
        "summary": "Get blockchain network details",
        "operationId": "getChain",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "chainId",
            "in": "path",
            "required": true,
            "description": "Standard EVM chain ID",
            "schema": {
              "type": "integer",
              "example": 1
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "Chain details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Chain"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      },
      "patch": {
        "tags": [
          "Chains"
        ],
        "summary": "Update blockchain network configuration",
        "operationId": "updateChain",
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "chainId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateChainInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "./common/responses.yaml#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "Updated chain",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Chain"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/orgs/{orgId}/wallets": {
      "get": {
        "tags": [
          "Wallets"
        ],
        "summary": "List organization wallets",
        "operationId": "listWallets",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "chainId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "List of wallets",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Wallet"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Wallets"
        ],
        "summary": "Register wallet for organization",
        "operationId": "createWallet",
        "x-event-types": [
          "wallet.created",
          "wallet.kyc.required"
        ],
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWalletInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "201": {
            "description": "Wallet created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/orgs/{orgId}/wallets/{walletId}": {
      "get": {
        "tags": [
          "Wallets"
        ],
        "summary": "Get wallet details",
        "operationId": "getWallet",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "walletId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "Wallet details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      },
      "patch": {
        "tags": [
          "Wallets"
        ],
        "summary": "Update wallet metadata",
        "operationId": "updateWallet",
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "name": "walletId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWalletInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "Updated wallet",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Wallet"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/orgs/{orgId}/onchain/txs": {
      "get": {
        "tags": [
          "OnChainTxs"
        ],
        "summary": "List on-chain transactions",
        "operationId": "listOnChainTxs",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          },
          {
            "name": "chainId",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "PENDING",
                "CONFIRMED",
                "FAILED"
              ]
            }
          },
          {
            "name": "refType",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "List of on-chain transactions",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/OnChainTx"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "OnChainTxs"
        ],
        "summary": "Register new on-chain transaction",
        "operationId": "createOnChainTx",
        "x-event-types": [
          "tx.confirmed",
          "tx.failed",
          "tx.reconciled"
        ],
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/orgId"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/orgIdHeader"
          },
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOnChainTxInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "201": {
            "description": "On-chain transaction created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OnChainTx"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/chain/adapters": {
      "get": {
        "tags": [
          "ChainAdapters"
        ],
        "summary": "List chain adapters",
        "operationId": "listChainAdapters",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/pagination.yaml#/components/parameters/cursor"
          },
          {
            "$ref": "./common/pagination.yaml#/components/parameters/limit"
          }
        ],
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "List of chain adapters",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "./common/pagination.yaml#/components/schemas/PageResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ChainAdapter"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "ChainAdapters"
        ],
        "summary": "Register chain adapter",
        "operationId": "createChainAdapter",
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "./common/components.yaml#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateChainAdapterInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "./common/responses.yaml#/components/responses/Conflict"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "201": {
            "description": "Chain adapter created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChainAdapter"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          }
        }
      }
    },
    "/chain/adapters/{adapterId}": {
      "get": {
        "tags": [
          "ChainAdapters"
        ],
        "summary": "Get chain adapter details",
        "operationId": "getChainAdapter",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "adapterId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Chain adapter details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChainAdapter"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      },
      "patch": {
        "tags": [
          "ChainAdapters"
        ],
        "summary": "Update adapter configuration",
        "operationId": "updateChainAdapter",
        "security": [
          {
            "oauth2": [
              "write:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "adapterId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateChainAdapterInput"
              }
            }
          }
        },
        "responses": {
          "400": {
            "$ref": "./common/responses.yaml#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "./common/responses.yaml#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "422": {
            "$ref": "./common/responses.yaml#/components/responses/ValidationError"
          },
          "429": {
            "$ref": "./common/responses.yaml#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          },
          "200": {
            "description": "Updated chain adapter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ChainAdapter"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/chain/adapters/{adapterId}/health": {
      "get": {
        "tags": [
          "ChainAdapters"
        ],
        "summary": "Check adapter health status",
        "operationId": "checkChainAdapterHealth",
        "x-event-types": [
          "adapter.health.degraded",
          "adapter.health.recovered"
        ],
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "parameters": [
          {
            "name": "adapterId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Adapter health metrics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/HealthMetrics"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "traceId": {
                          "type": "string",
                          "example": "trace-550e8400-e29b-41d4-a716"
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "./common/responses.yaml#/components/responses/NotFound"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    },
    "/chain/health": {
      "get": {
        "tags": [
          "ChainAdapters"
        ],
        "summary": "Overall chain service health",
        "operationId": "checkChainServiceHealth",
        "security": [
          {
            "oauth2": [
              "read:chain"
            ]
          },
          {
            "apiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Service health summary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "HEALTHY",
                            "DEGRADED",
                            "DOWN"
                          ],
                          "example": "HEALTHY"
                        },
                        "adaptersHealthy": {
                          "type": "integer",
                          "example": 8
                        },
                        "adaptersDegraded": {
                          "type": "integer",
                          "example": 1
                        },
                        "adaptersDown": {
                          "type": "integer",
                          "example": 0
                        },
                        "chains": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "chainId": {
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "HEALTHY",
                                  "DEGRADED",
                                  "DOWN"
                                ]
                              }
                            }
                          }
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "./common/responses.yaml#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "./common/responses.yaml#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "$ref": "./common/components.yaml#/components/securitySchemes/bearerAuth"
      },
      "oauth2": {
        "$ref": "./common/components.yaml#/components/securitySchemes/oauth2",
        "x-scopes": {
          "read:chain": "Read access to chain data",
          "write:chain": "Write access to chain resources",
          "chain.audit": "Access audit logs",
          "wallet.write": "Create and update wallets",
          "wallet.read": "Read wallet information"
        }
      },
      "apiKey": {
        "$ref": "./common/components.yaml#/components/securitySchemes/apiKey"
      }
    },
    "schemas": {
      "Chain": {
        "type": "object",
        "description": "Master registry of blockchain networks (system-wide reference data).",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "chainId": {
            "type": "integer",
            "description": "Standard EVM chain ID (https://chainlist.org)",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Human-readable chain name",
            "example": "Ethereum Mainnet"
          },
          "shortName": {
            "type": "string",
            "description": "Short identifier",
            "example": "ETH"
          },
          "networkType": {
            "type": "string",
            "enum": [
              "MAINNET",
              "TESTNET",
              "DEVNET"
            ],
            "example": "MAINNET"
          },
          "layer": {
            "type": "string",
            "enum": [
              "L1",
              "L2"
            ],
            "description": "Layer 1 or Layer 2",
            "example": "L1"
          },
          "nativeCurrency": {
            "type": "string",
            "description": "Native token symbol",
            "example": "ETH"
          },
          "decimals": {
            "type": "integer",
            "description": "Native currency decimals",
            "example": 18,
            "default": 18
          },
          "blockTime": {
            "type": "integer",
            "description": "Average block time in seconds",
            "example": 12
          },
          "confirmations": {
            "type": "integer",
            "description": "Required confirmations for finality",
            "example": 12,
            "default": 12
          },
          "explorerUrl": {
            "type": "string",
            "format": "uri",
            "description": "Block explorer URL",
            "example": "https://etherscan.io"
          },
          "docsUrl": {
            "type": "string",
            "format": "uri",
            "description": "Official documentation URL",
            "example": "https://ethereum.org/en/developers/docs/"
          },
          "iconUrl": {
            "type": "string",
            "format": "uri",
            "description": "Chain icon/logo URL"
          },
          "genesisHash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$",
            "description": "Genesis block hash for chain fingerprinting and integrity validation",
            "example": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3"
          },
          "chainNamespace": {
            "type": "string",
            "enum": [
              "EVM",
              "COSMOS",
              "SOLANA",
              "POLKADOT"
            ],
            "description": "Blockchain namespace for multi-chain support",
            "example": "EVM",
            "default": "EVM"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DEPRECATED",
              "DISABLED"
            ],
            "example": "ACTIVE"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "deprecationReason": {
            "type": "string",
            "description": "Explanation for deprecation (e.g., \"Migrated to post-merge Ethereum\")",
            "example": "Network upgraded to Proof-of-Stake"
          },
          "replacedBy": {
            "type": "integer",
            "description": "Chain ID that replaces this deprecated chain",
            "example": 1
          },
          "createdBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or user that created this chain",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "updatedBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or user that last updated this chain",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          }
        },
        "required": [
          "id",
          "chainId",
          "name",
          "shortName",
          "networkType",
          "layer",
          "nativeCurrency",
          "status"
        ]
      },
      "Wallet": {
        "type": "object",
        "description": "Represents a blockchain wallet under an organization or account.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440001"
          },
          "orgId": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440002"
          },
          "ownerAccountId": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440003"
          },
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Blockchain address (Ethereum format)",
            "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
          },
          "type": {
            "type": "string",
            "enum": [
              "CUSTODIAL",
              "NON_CUSTODIAL",
              "MPC",
              "HARDWARE"
            ],
            "example": "MPC"
          },
          "label": {
            "type": "string",
            "description": "User-defined label",
            "example": "Trading Wallet"
          },
          "chainId": {
            "type": "integer",
            "description": "Reference to Chain.chainId",
            "example": 1
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISABLED",
              "ARCHIVED"
            ],
            "example": "ACTIVE"
          },
          "derivationPath": {
            "type": "string",
            "description": "HD wallet derivation path (BIP-44)",
            "example": "m/44'/60'/0'/0/0"
          },
          "parentWalletId": {
            "type": "string",
            "format": "uuid",
            "description": "Parent HD wallet reference",
            "example": "550e8400-e29b-41d4-a716-446655440004"
          },
          "walletIndex": {
            "type": "integer",
            "description": "Index in HD wallet sequence",
            "example": 0
          },
          "kycStatus": {
            "type": "string",
            "enum": [
              "PENDING",
              "VERIFIED",
              "REJECTED",
              "NOT_REQUIRED"
            ],
            "description": "KYC verification status for compliance",
            "example": "VERIFIED"
          },
          "jurisdiction": {
            "type": "string",
            "description": "Regulatory jurisdiction (ISO 3166-1 alpha-2)",
            "example": "US"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "source": {
            "type": "string",
            "enum": [
              "MANUAL",
              "IMPORTED",
              "CUSTODIAL_API",
              "MPC_CLUSTER"
            ],
            "description": "How this wallet was created",
            "example": "MPC_CLUSTER"
          },
          "createdBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or user that created this wallet"
          },
          "updatedBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or user that last updated this wallet"
          }
        },
        "required": [
          "id",
          "orgId",
          "address",
          "type",
          "chainId",
          "status"
        ]
      },
      "OnChainTx": {
        "type": "object",
        "description": "On-chain transaction record with full metadata.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440010"
          },
          "orgId": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440002"
          },
          "chainId": {
            "type": "integer",
            "description": "Reference to Chain.chainId",
            "example": 1
          },
          "hash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$",
            "description": "Transaction hash",
            "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
          },
          "fromAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Sender address",
            "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
          },
          "toAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Recipient address",
            "example": "0x1234567890123456789012345678901234567890"
          },
          "direction": {
            "type": "string",
            "enum": [
              "INBOUND",
              "OUTBOUND"
            ],
            "example": "OUTBOUND"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "CONFIRMED",
              "FAILED"
            ],
            "example": "CONFIRMED"
          },
          "amount": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Transaction amount (stringified base units to avoid precision loss)",
            "example": "1500000000000000000"
          },
          "assetType": {
            "type": "string",
            "enum": [
              "NATIVE",
              "ERC20",
              "ERC721",
              "ERC1155"
            ],
            "description": "Type of asset transferred",
            "example": "ERC20"
          },
          "tokenAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Smart contract address for tokens (ERC-20/721/1155)",
            "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
          },
          "tokenId": {
            "type": "string",
            "description": "Token ID for NFTs (ERC-721/1155)",
            "example": "12345"
          },
          "decimals": {
            "type": "integer",
            "description": "Token decimals (e.g., 6 for USDC, 18 for most ERC-20)",
            "example": 6
          },
          "blockNumber": {
            "type": "integer",
            "description": "Block number where transaction was included",
            "example": 15000000
          },
          "blockTime": {
            "type": "string",
            "format": "date-time",
            "description": "Block timestamp"
          },
          "gasUsed": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Gas units consumed (stringified to avoid precision loss)",
            "example": "21000"
          },
          "gasPrice": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Gas price in wei (stringified to avoid precision loss)",
            "example": "50000000000"
          },
          "txFeeAmount": {
            "type": "string",
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "description": "Transaction fee in native currency (stringified to avoid precision loss)",
            "example": "0.00105"
          },
          "txFeeUsd": {
            "type": "string",
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "description": "Transaction fee in USD at time of tx (stringified to avoid precision loss)",
            "example": "2.45"
          },
          "nonce": {
            "type": "integer",
            "description": "Transaction nonce",
            "example": 42
          },
          "refType": {
            "type": "string",
            "description": "Reference to entity type (e.g., ESCROW, SETTLEMENT)",
            "example": "SETTLEMENT"
          },
          "refId": {
            "type": "string",
            "format": "uuid",
            "description": "Reference to entity ID",
            "example": "550e8400-e29b-41d4-a716-446655440020"
          },
          "source": {
            "type": "string",
            "enum": [
              "NODE",
              "WEBHOOK",
              "INDEXER",
              "MANUAL"
            ],
            "description": "Origin of transaction record for auditability",
            "example": "INDEXER"
          },
          "syncVersion": {
            "type": "string",
            "description": "Sync batch or version identifier for reconciliation",
            "example": "sync-2024-10-28-001"
          },
          "rawTx": {
            "type": "object",
            "description": "Raw transaction data from blockchain (JSON)"
          },
          "logs": {
            "type": "array",
            "description": "Event logs emitted by transaction",
            "items": {
              "type": "object"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "confirmations": {
            "type": "integer",
            "description": "Number of block confirmations received",
            "example": 12
          },
          "finalized": {
            "type": "boolean",
            "description": "Whether transaction has reached finality per chain rules",
            "example": true
          },
          "fiatRateSource": {
            "type": "string",
            "enum": [
              "COINGECKO",
              "CHAINLINK",
              "BINANCE",
              "INTERNAL"
            ],
            "description": "Source of fiat rate used for txFeeUsd calculation",
            "example": "CHAINLINK"
          },
          "fiatRateTimestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of fiat rate snapshot"
          },
          "createdBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or indexer that created this transaction record"
          }
        },
        "required": [
          "id",
          "orgId",
          "chainId",
          "hash",
          "status"
        ]
      },
      "ChainAdapter": {
        "type": "object",
        "description": "Blockchain network adapter configuration (RPC connection details).",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440030"
          },
          "chainId": {
            "type": "integer",
            "description": "Reference to Chain.chainId",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Adapter identifier (e.g., 'Alchemy Primary', 'Infura Backup')",
            "example": "Alchemy Primary"
          },
          "rpcEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "HTTP RPC endpoint URL",
            "example": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
          },
          "wsEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "WebSocket endpoint URL (optional)",
            "example": "wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
          },
          "signerPolicy": {
            "type": "string",
            "enum": [
              "LOCAL_SIGNER",
              "MPC_CLUSTER",
              "HSM",
              "FIREBLOCKS",
              "CUSTODY_PROVIDER"
            ],
            "description": "Transaction signing strategy",
            "example": "MPC_CLUSTER"
          },
          "priority": {
            "type": "integer",
            "description": "Adapter priority (0 = primary, higher = fallback)",
            "example": 0,
            "default": 0
          },
          "fallbackAdapterIds": {
            "type": "array",
            "description": "Ordered list of fallback adapter IDs for redundancy",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "example": [
              "550e8400-e29b-41d4-a716-446655440031"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISABLED",
              "MAINTENANCE"
            ],
            "example": "ACTIVE"
          },
          "lastHealthCheck": {
            "type": "string",
            "format": "date-time",
            "description": "Last health check timestamp"
          },
          "healthStatus": {
            "type": "object",
            "description": "Health check metrics (JSON)",
            "properties": {
              "latency": {
                "type": "integer",
                "description": "Response latency in ms",
                "example": 50
              },
              "blockHeight": {
                "type": "integer",
                "description": "Current block height",
                "example": 15000000
              },
              "synced": {
                "type": "boolean",
                "description": "Is node fully synced",
                "example": true
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or user that created this adapter"
          },
          "updatedBy": {
            "type": "string",
            "format": "uuid",
            "description": "Service or user that last updated this adapter"
          }
        },
        "required": [
          "id",
          "chainId",
          "name",
          "rpcEndpoint",
          "signerPolicy",
          "status"
        ]
      },
      "CreateChainInput": {
        "type": "object",
        "description": "Input for creating a new blockchain network in the registry",
        "required": [
          "chainId",
          "name",
          "shortName",
          "networkType",
          "layer",
          "nativeCurrency"
        ],
        "properties": {
          "chainId": {
            "type": "integer",
            "description": "Standard EVM chain ID (https://chainlist.org)",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Human-readable chain name",
            "example": "Ethereum Mainnet"
          },
          "shortName": {
            "type": "string",
            "description": "Short identifier",
            "example": "ETH"
          },
          "networkType": {
            "type": "string",
            "enum": [
              "MAINNET",
              "TESTNET",
              "DEVNET"
            ],
            "example": "MAINNET"
          },
          "layer": {
            "type": "string",
            "enum": [
              "L1",
              "L2"
            ],
            "description": "Layer 1 or Layer 2",
            "example": "L1"
          },
          "nativeCurrency": {
            "type": "string",
            "description": "Native token symbol",
            "example": "ETH"
          },
          "decimals": {
            "type": "integer",
            "description": "Native currency decimals",
            "example": 18,
            "default": 18
          },
          "blockTime": {
            "type": "integer",
            "description": "Average block time in seconds",
            "example": 12
          },
          "confirmations": {
            "type": "integer",
            "description": "Required confirmations for finality",
            "example": 12,
            "default": 12
          },
          "explorerUrl": {
            "type": "string",
            "format": "uri",
            "description": "Block explorer URL",
            "example": "https://etherscan.io"
          },
          "docsUrl": {
            "type": "string",
            "format": "uri",
            "description": "Official documentation URL",
            "example": "https://ethereum.org/en/developers/docs/"
          },
          "iconUrl": {
            "type": "string",
            "format": "uri",
            "description": "Chain icon/logo URL"
          },
          "genesisHash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$",
            "description": "Genesis block hash for chain fingerprinting",
            "example": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3"
          },
          "chainNamespace": {
            "type": "string",
            "enum": [
              "EVM",
              "COSMOS",
              "SOLANA",
              "POLKADOT"
            ],
            "description": "Blockchain namespace for multi-chain support",
            "example": "EVM",
            "default": "EVM"
          }
        }
      },
      "UpdateChainInput": {
        "type": "object",
        "description": "Input for updating an existing blockchain network configuration",
        "minProperties": 1,
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable chain name",
            "example": "Ethereum Mainnet"
          },
          "shortName": {
            "type": "string",
            "description": "Short identifier",
            "example": "ETH"
          },
          "blockTime": {
            "type": "integer",
            "description": "Average block time in seconds",
            "example": 12
          },
          "confirmations": {
            "type": "integer",
            "description": "Required confirmations for finality",
            "example": 12
          },
          "explorerUrl": {
            "type": "string",
            "format": "uri",
            "description": "Block explorer URL",
            "example": "https://etherscan.io"
          },
          "docsUrl": {
            "type": "string",
            "format": "uri",
            "description": "Official documentation URL",
            "example": "https://ethereum.org/en/developers/docs/"
          },
          "iconUrl": {
            "type": "string",
            "format": "uri",
            "description": "Chain icon/logo URL"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DEPRECATED",
              "DISABLED"
            ],
            "example": "ACTIVE"
          }
        }
      },
      "CreateWalletInput": {
        "type": "object",
        "description": "Input for creating a new wallet",
        "required": [
          "address",
          "type",
          "chainId"
        ],
        "properties": {
          "ownerAccountId": {
            "type": "string",
            "format": "uuid",
            "description": "Account that owns this wallet",
            "example": "550e8400-e29b-41d4-a716-446655440003"
          },
          "address": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Blockchain address (Ethereum format)",
            "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
          },
          "type": {
            "type": "string",
            "enum": [
              "CUSTODIAL",
              "NON_CUSTODIAL",
              "MPC",
              "HARDWARE"
            ],
            "example": "MPC"
          },
          "label": {
            "type": "string",
            "description": "User-defined label",
            "example": "Trading Wallet"
          },
          "chainId": {
            "type": "integer",
            "description": "Reference to Chain.chainId",
            "example": 1
          },
          "derivationPath": {
            "type": "string",
            "description": "HD wallet derivation path (BIP-44)",
            "example": "m/44'/60'/0'/0/0"
          },
          "parentWalletId": {
            "type": "string",
            "format": "uuid",
            "description": "Parent HD wallet reference",
            "example": "550e8400-e29b-41d4-a716-446655440004"
          },
          "walletIndex": {
            "type": "integer",
            "description": "Index in HD wallet sequence",
            "example": 0
          },
          "jurisdiction": {
            "type": "string",
            "description": "Regulatory jurisdiction (ISO 3166-1 alpha-2)",
            "example": "US"
          }
        }
      },
      "UpdateWalletInput": {
        "type": "object",
        "description": "Input for updating an existing wallet",
        "minProperties": 1,
        "properties": {
          "label": {
            "type": "string",
            "description": "User-defined label",
            "example": "Trading Wallet"
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISABLED",
              "ARCHIVED"
            ],
            "example": "ACTIVE"
          }
        }
      },
      "CreateOnChainTxInput": {
        "type": "object",
        "description": "Input for recording a new on-chain transaction",
        "required": [
          "chainId",
          "hash"
        ],
        "properties": {
          "chainId": {
            "type": "integer",
            "description": "Reference to Chain.chainId",
            "example": 1
          },
          "hash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$",
            "description": "Transaction hash",
            "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
          },
          "fromAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Sender address",
            "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
          },
          "toAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Recipient address",
            "example": "0x1234567890123456789012345678901234567890"
          },
          "direction": {
            "type": "string",
            "enum": [
              "INBOUND",
              "OUTBOUND"
            ],
            "example": "OUTBOUND"
          },
          "amount": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Transaction amount (stringified base units to avoid precision loss)",
            "example": "1500000000000000000"
          },
          "assetType": {
            "type": "string",
            "enum": [
              "NATIVE",
              "ERC20",
              "ERC721",
              "ERC1155"
            ],
            "description": "Type of asset transferred",
            "example": "ERC20"
          },
          "tokenAddress": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Smart contract address for tokens (ERC-20/721/1155)",
            "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
          },
          "tokenId": {
            "type": "string",
            "description": "Token ID for NFTs (ERC-721/1155)",
            "example": "12345"
          },
          "decimals": {
            "type": "integer",
            "description": "Token decimals (e.g., 6 for USDC, 18 for most ERC-20)",
            "example": 6
          },
          "blockNumber": {
            "type": "integer",
            "description": "Block number where transaction was included",
            "example": 15000000
          },
          "gasPrice": {
            "type": "string",
            "pattern": "^[0-9]+$",
            "description": "Gas price in wei (stringified to avoid precision loss)",
            "example": "50000000000"
          },
          "nonce": {
            "type": "integer",
            "description": "Transaction nonce",
            "example": 42
          },
          "txFeeAmount": {
            "type": "string",
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "description": "Transaction fee in native currency (stringified to avoid precision loss)",
            "example": "0.00105"
          },
          "txFeeUsd": {
            "type": "string",
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "description": "Transaction fee in USD at time of tx (stringified to avoid precision loss)",
            "example": "2.45"
          },
          "refType": {
            "type": "string",
            "description": "Reference to entity type (e.g., ESCROW, SETTLEMENT)",
            "example": "SETTLEMENT"
          },
          "refId": {
            "type": "string",
            "format": "uuid",
            "description": "Reference to entity ID",
            "example": "550e8400-e29b-41d4-a716-446655440020"
          },
          "source": {
            "type": "string",
            "enum": [
              "NODE",
              "WEBHOOK",
              "INDEXER",
              "MANUAL"
            ],
            "description": "Origin of transaction record for auditability",
            "example": "INDEXER",
            "default": "MANUAL"
          },
          "syncVersion": {
            "type": "string",
            "description": "Sync batch or version identifier for reconciliation",
            "example": "sync-2024-10-28-001"
          }
        }
      },
      "CreateChainAdapterInput": {
        "type": "object",
        "description": "Input for registering a new blockchain adapter (RPC connection)",
        "required": [
          "chainId",
          "name",
          "rpcEndpoint",
          "signerPolicy"
        ],
        "properties": {
          "chainId": {
            "type": "integer",
            "description": "Reference to Chain.chainId",
            "example": 1
          },
          "name": {
            "type": "string",
            "description": "Adapter identifier (e.g., 'Alchemy Primary', 'Infura Backup')",
            "example": "Alchemy Primary"
          },
          "rpcEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "HTTP RPC endpoint URL",
            "example": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
          },
          "wsEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "WebSocket endpoint URL (optional)",
            "example": "wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
          },
          "signerPolicy": {
            "type": "string",
            "enum": [
              "LOCAL_SIGNER",
              "MPC_CLUSTER",
              "HSM",
              "FIREBLOCKS",
              "CUSTODY_PROVIDER"
            ],
            "description": "Transaction signing strategy",
            "example": "MPC_CLUSTER"
          },
          "priority": {
            "type": "integer",
            "description": "Adapter priority (0 = primary, higher = fallback)",
            "example": 0,
            "default": 0
          },
          "fallbackAdapterIds": {
            "type": "array",
            "description": "Ordered list of fallback adapter IDs for redundancy",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "example": [
              "550e8400-e29b-41d4-a716-446655440031"
            ]
          }
        }
      },
      "UpdateChainAdapterInput": {
        "type": "object",
        "description": "Input for updating an existing blockchain adapter configuration",
        "minProperties": 1,
        "properties": {
          "rpcEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "HTTP RPC endpoint URL",
            "example": "https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
          },
          "wsEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "WebSocket endpoint URL (optional)",
            "example": "wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY"
          },
          "priority": {
            "type": "integer",
            "description": "Adapter priority (0 = primary, higher = fallback)",
            "example": 0
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "DISABLED",
              "MAINTENANCE"
            ],
            "example": "ACTIVE"
          },
          "healthStatus": {
            "type": "object",
            "description": "Health check metrics (JSON)",
            "properties": {
              "latency": {
                "type": "integer",
                "description": "Response latency in ms",
                "example": 50
              },
              "blockHeight": {
                "type": "integer",
                "description": "Current block height",
                "example": 15000000
              },
              "synced": {
                "type": "boolean",
                "description": "Is node fully synced",
                "example": true
              }
            }
          }
        }
      },
      "HealthMetrics": {
        "type": "object",
        "description": "Health check metrics for blockchain adapters",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "HEALTHY",
              "DEGRADED",
              "DOWN"
            ],
            "example": "HEALTHY"
          },
          "latencyMs": {
            "type": "integer",
            "description": "Current RPC response latency",
            "example": 45
          },
          "blockHeight": {
            "type": "integer",
            "description": "Latest block number",
            "example": 18500000
          },
          "syncLag": {
            "type": "integer",
            "description": "Blocks behind network tip",
            "example": 0
          },
          "uptime": {
            "type": "number",
            "description": "Uptime percentage (last 24h)",
            "example": 99.95
          },
          "lastChecked": {
            "type": "string",
            "format": "date-time",
            "description": "Last health check timestamp"
          }
        }
      }
    }
  }
}