---
updatedAt: 2026-11-10T10:03:38.000Z
agentTools:
  projectIndex: https://developers.tron.network/llms.txt
---

# CreateWitness

Build an unsigned transaction to apply as an SR candidate; successful registration execution incurs a one-time fee.

> ⚠️ **SR candidate registration fee**
>
> Building an unsigned transaction does not deduct a fee. A one-time fee is charged and burned when the registration transaction executes successfully; it is not a refundable deposit. The fee is currently **9,999 TRX on Mainnet**, set by the `getAccountUpgradeCost` chain parameter and available via [`wallet/getchainparameters`](https://developers.tron.network/reference/wallet-getchainparameters).

## Related resources

* [Listwitnesses](https://developers.tron.network/reference/listwitnesses) — previous in this section
* [Updatewitness](https://developers.tron.network/reference/updatewitness) — next in this section
* [Voting for SRs](https://developers.tron.network/docs/voting-for-srs) — voting mechanics and per-cycle reward snapshots
* [Super Representatives](https://developers.tron.network/docs/super-representatives) — SR role, 27 active / 127 ranked

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "full-node-http-api",
    "version": "4.8.0"
  },
  "servers": [
    {
      "url": "https://api.shasta.trongrid.io",
      "description": "Shasta Testnet"
    },
    {
      "url": "https://nile.trongrid.io",
      "description": "Nile Testnet"
    },
    {
      "url": "https://api.trongrid.io",
      "description": "Mainnet (real assets)"
    }
  ],
  "components": {
    "schemas": {
      "NodeHttpBusinessError": {
        "title": "Error",
        "type": "object",
        "description": "When request processing fails, java-tron may return this format with HTTP 200; the `Error` field contains the error details.",
        "required": [
          "Error"
        ],
        "properties": {
          "Error": {
            "type": "string",
            "description": "Error text returned by java-tron."
          }
        },
        "examples": [
          {
            "Error": "Invalid request parameters."
          }
        ],
        "additionalProperties": false
      },
      "StringInt64MapEntry": {
        "type": "object",
        "description": "Map entry. TRON's HTTP API serializes protobuf `map<string, int64>` as an array of `{key, value}` objects (rather than a JSON object with dynamic keys).",
        "properties": {
          "key": {
            "type": "string"
          },
          "value": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "Transaction": {
        "type": "object",
        "description": "TRON transaction object. See [wallet-gettransactionbyid](ref:wallet-gettransactionbyid) for full structure.",
        "properties": {
          "txID": {
            "type": "string",
            "description": "SHA-256 transaction identifier computed from the protobuf-encoded raw_data."
          },
          "raw_data": {
            "$ref": "#/components/schemas/TransactionRawData"
          },
          "raw_data_hex": {
            "type": "string"
          },
          "signature": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ret": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "fee": {
                  "type": "integer",
                  "format": "int64"
                },
                "ret": {
                  "type": "string",
                  "enum": [
                    "SUCESS",
                    "FAILED"
                  ]
                },
                "contractRet": {
                  "type": "string"
                },
                "assetIssueID": {
                  "type": "string"
                },
                "withdraw_amount": {
                  "type": "integer",
                  "format": "int64"
                },
                "unfreeze_amount": {
                  "type": "integer",
                  "format": "int64"
                },
                "exchange_received_amount": {
                  "type": "integer",
                  "format": "int64"
                },
                "exchange_inject_another_amount": {
                  "type": "integer",
                  "format": "int64"
                },
                "exchange_withdraw_another_amount": {
                  "type": "integer",
                  "format": "int64"
                },
                "exchange_id": {
                  "type": "integer",
                  "format": "int64"
                },
                "shielded_transaction_fee": {
                  "type": "integer",
                  "format": "int64"
                },
                "orderId": {
                  "type": "string"
                },
                "orderDetails": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MarketOrderDetail"
                  }
                },
                "withdraw_expire_amount": {
                  "type": "integer",
                  "format": "int64"
                },
                "cancel_unfreezeV2_amount": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StringInt64MapEntry"
                  }
                }
              }
            }
          },
          "visible": {
            "type": "boolean"
          }
        }
      },
      "TransactionAuthority": {
        "type": "object",
        "description": "Authorized account identifier stored in transaction raw_data.",
        "properties": {
          "account": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "address": {
                "type": "string"
              }
            }
          },
          "permission_name": {
            "type": "string"
          }
        }
      },
      "MarketOrderDetail": {
        "type": "object",
        "description": "Market-order match detail.",
        "properties": {
          "makerOrderId": {
            "type": "string"
          },
          "takerOrderId": {
            "type": "string"
          },
          "fillSellQuantity": {
            "type": "integer",
            "format": "int64"
          },
          "fillBuyQuantity": {
            "type": "integer",
            "format": "int64"
          }
        }
      },
      "TransactionRawData": {
        "type": "object",
        "description": "Unsigned transaction data covered by the transaction signature and txID.",
        "properties": {
          "ref_block_bytes": {
            "type": "string"
          },
          "ref_block_num": {
            "type": "integer",
            "format": "int64"
          },
          "ref_block_hash": {
            "type": "string"
          },
          "expiration": {
            "type": "integer",
            "format": "int64"
          },
          "auths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TransactionAuthority"
            }
          },
          "data": {
            "type": "string"
          },
          "contract": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "parameter": {
                  "type": "object",
                  "properties": {
                    "type_url": {
                      "type": "string"
                    },
                    "value": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                },
                "provider": {
                  "type": "string"
                },
                "ContractName": {
                  "type": "string"
                },
                "Permission_id": {
                  "type": "integer",
                  "format": "int32"
                }
              }
            }
          },
          "scripts": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer",
            "format": "int64"
          },
          "fee_limit": {
            "type": "integer",
            "format": "int64"
          }
        }
      }
    }
  },
  "security": [
    {}
  ],
  "paths": {
    "/wallet/createwitness": {
      "post": {
        "summary": "CreateWitness",
        "description": "Apply to become a super representative candidate.",
        "operationId": "createwitness",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "owner_address": {
                    "type": "string",
                    "description": "Existing account applying to become an SR candidate, in Base58 or Hex format.",
                    "default": ""
                  },
                  "url": {
                    "type": "string",
                    "description": "Official website URL. With the default `visible=false`, provide Hex-encoded UTF-8 bytes, such as `68747470733a2f2f6578616d706c652e636f6d`; with `visible=true`, provide text such as `https://example.com`.",
                    "default": ""
                  },
                  "Permission_id": {
                    "type": "integer",
                    "description": "Optional. Permission ID used for multi-signature account operations. Defaults to the owner permission (0) if unspecified.",
                    "format": "int32"
                  },
                  "visible": {
                    "type": "boolean",
                    "description": "Optional. Set to `true` to format addresses in Base58; set to `false` for hex format. (Default: `false`)"
                  }
                },
                "required": [
                  "owner_address",
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "On successful validation, returns an unsigned transaction containing `txID`, `raw_data`, and `raw_data_hex`, not a `TransactionExtention` wrapper. Construction alone does not change on-chain state; signing, broadcasting, and successful on-chain execution are required. Validation or parsing failures can return a string `Error` with HTTP 200. The response is a transaction to apply as an SR candidate, not proof of successful registration or selection as a block-producing SR. Construction itself does not charge the registration fee. `url` uses Hex-encoded UTF-8 bytes by default; with `visible=true`, text can be used.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "title": "Result",
                      "not": {
                        "type": "object",
                        "required": [
                          "Error"
                        ]
                      },
                      "$ref": "#/components/schemas/Transaction"
                    },
                    {
                      "$ref": "#/components/schemas/NodeHttpBusinessError"
                    }
                  ]
                },
                "examples": {
                  "success": {
                    "summary": "Unsigned transaction: Hex addresses (complete response)",
                    "description": "Request body: `{\"owner_address\":\"416f819f9169c5a5b03bc15757f4831a1af7c959d9\",\"url\":\"68747470733a2f2f6578616d706c652e636f6d\"}`. Complete unsigned transaction response; it has not been signed or broadcast. Build a fresh transaction for actual use instead of reusing the example's reference block or expiration.",
                    "value": {
                      "raw_data": {
                        "ref_block_bytes": "8e0c",
                        "ref_block_hash": "9bf0018ab962781a",
                        "expiration": 1794293457000,
                        "contract": [
                          {
                            "parameter": {
                              "value": {
                                "owner_address": "416f819f9169c5a5b03bc15757f4831a1af7c959d9",
                                "url": "68747470733a2f2f6578616d706c652e636f6d"
                              },
                              "type_url": "type.googleapis.com/protocol.WitnessCreateContract"
                            },
                            "type": "WitnessCreateContract"
                          }
                        ],
                        "timestamp": 1794293399012
                      },
                      "raw_data_hex": "0a028e0c22089bf0018ab962781a40e8c0e5a19c345a66080512620a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5769746e657373437265617465436f6e7472616374122c0a15416f819f9169c5a5b03bc15757f4831a1af7c959d9121368747470733a2f2f6578616d706c652e636f6d70e4fbe1a19c34",
                      "txID": "2173a19688aca646c21381d39274fd2f4c66c4260719f92b0c3b5a710d01d617",
                      "visible": false
                    }
                  },
                  "visible": {
                    "summary": "Unsigned transaction: Base58 addresses (complete response)",
                    "description": "Request body: `{\"owner_address\":\"TL8oHjkJTzqEPbKMRVuEVZNwzdgBNPhWd5\",\"url\":\"https://example.com\",\"visible\":true}`. With `visible=true`, addresses in the transaction parameters use Base58. In this example, `url` also uses text, not Hex.",
                    "value": {
                      "raw_data": {
                        "ref_block_bytes": "8e0c",
                        "ref_block_hash": "9bf0018ab962781a",
                        "expiration": 1794293457000,
                        "contract": [
                          {
                            "parameter": {
                              "value": {
                                "owner_address": "TL8oHjkJTzqEPbKMRVuEVZNwzdgBNPhWd5",
                                "url": "https://example.com"
                              },
                              "type_url": "type.googleapis.com/protocol.WitnessCreateContract"
                            },
                            "type": "WitnessCreateContract"
                          }
                        ],
                        "timestamp": 1794293399017
                      },
                      "raw_data_hex": "0a028e0c22089bf0018ab962781a40e8c0e5a19c345a66080512620a32747970652e676f6f676c65617069732e636f6d2f70726f746f636f6c2e5769746e657373437265617465436f6e7472616374122c0a15416f819f9169c5a5b03bc15757f4831a1af7c959d9121368747470733a2f2f6578616d706c652e636f6d70e9fbe1a19c34",
                      "txID": "2e9f02babb571fd9b96221f2a8f301c4e771f3d981fabf9c1830f1e9187ca4e7",
                      "visible": true
                    }
                  },
                  "existingWitness": {
                    "summary": "Account already registered as a candidate (HTTP 200)",
                    "description": "Request body: `{\"owner_address\":\"41ce8a0cf0c16d48bcf22825f6053248df653c89ca\",\"url\":\"68747470733a2f2f6578616d706c652e636f6d\"}`. The HTTP status is 200 and `Error` is a string. Error text is preserved exactly as returned and may vary by node version.",
                    "value": {
                      "Error": "class org.tron.core.exception.ContractValidateException : Witness[41ce8a0cf0c16d48bcf22825f6053248df653c89ca] has existed"
                    }
                  },
                  "lowBalance": {
                    "summary": "Insufficient balance for the registration fee (HTTP 200)",
                    "description": "Request body: `{\"owner_address\":\"41cbe603e1f0ac26c50bb795d8d54a95706c64b2e2\",\"url\":\"68747470733a2f2f6578616d706c652e636f6d\"}`. Construction checks the balance but does not deduct the fee. The HTTP status is 200 and `Error` is a string. Error text is preserved exactly as returned and may vary by node version.",
                    "value": {
                      "Error": "class org.tron.core.exception.ContractValidateException : balance < AccountUpgradeCost"
                    }
                  },
                  "emptyUrl": {
                    "summary": "Empty URL (HTTP 200)",
                    "description": "Request body: `{\"owner_address\":\"416f819f9169c5a5b03bc15757f4831a1af7c959d9\",\"url\":\"\"}`. The HTTP status is 200 and `Error` is a string. Error text is preserved exactly as returned and may vary by node version.",
                    "value": {
                      "Error": "class org.tron.core.exception.ContractValidateException : Invalid url"
                    }
                  },
                  "plainUrl": {
                    "summary": "URL text with the default encoding (HTTP 200)",
                    "description": "Request body: `{\"owner_address\":\"416f819f9169c5a5b03bc15757f4831a1af7c959d9\",\"url\":\"https://example.com\"}`. Without `visible=true`, the URL text is parsed as Hex and fails. The HTTP status is 200 and `Error` is a string. Error text is preserved exactly as returned and may vary by node version.",
                    "value": {
                      "Error": "class org.tron.core.services.http.JsonFormat$ParseException : 1:69: INVALID hex String"
                    }
                  },
                  "invalidBase58": {
                    "summary": "Invalid Base58 address (HTTP 200)",
                    "description": "Request body: `{\"owner_address\":\"not-an-address\",\"url\":\"https://example.com\",\"visible\":true}`. The HTTP status is 200 and `Error` is a string. Error text is preserved exactly as returned and may vary by node version.",
                    "value": {
                      "Error": "class org.tron.core.services.http.JsonFormat$ParseException : 1:18: invalid address for field: protocol.WitnessCreateContract.owner_address"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```