# RPC API v1

Use these endpoints to read ledger state and submit transactions.

### Network State

## Get current TXV

> Returns the current transaction validity hash (\`txv\`) as hex.

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Network"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/txv":{"get":{"tags":["Network"],"summary":"Get current TXV","description":"Returns the current transaction validity hash (`txv`) as hex.","responses":{"200":{"description":"TXV returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxvResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"TxvResponse":{"type":"object","required":["txv"],"properties":{"txv":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

#### Get fee

Returns the fee used for transaction submission.

## GET /v1/fee

> Get current transaction fee

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Network"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/fee":{"get":{"tags":["Network"],"summary":"Get current transaction fee","responses":{"200":{"description":"Fee returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"FeeResponse":{"type":"object","required":["fee"],"properties":{"fee":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

#### Get confirmed length

Returns the current confirmed ledger length.

## GET /v1/confirmed-length

> Get confirmed ledger length

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Network"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/confirmed-length":{"get":{"tags":["Network"],"summary":"Get confirmed ledger length","responses":{"200":{"description":"Confirmed length returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmedLengthResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"ConfirmedLengthResponse":{"type":"object","required":["confirmed_length"],"properties":{"confirmed_length":{"type":"integer"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

#### Get unconfirmed length

Returns the current unconfirmed ledger length.

## GET /v1/unconfirmed-length

> Get unconfirmed ledger length

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Network"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/unconfirmed-length":{"get":{"tags":["Network"],"summary":"Get unconfirmed ledger length","responses":{"200":{"description":"Unconfirmed length returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnconfirmedLengthResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"UnconfirmedLengthResponse":{"type":"object","required":["unconfirmed_length"],"properties":{"unconfirmed_length":{"type":"integer"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

### Wallet & Account

#### Get balance

Returns the current balance for an address.

## Get wallet balance

> Returns balance for the specified wallet address.\
> \
> \`confirmed\` query behavior:\
> \- missing: defaults to confirmed view\
> \- \`true\`: confirmed view\
> \- \`false\`: unconfirmed view\
> \- any other value: falls back to unconfirmed view<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Wallet"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/balance/{address}":{"get":{"tags":["Wallet"],"summary":"Get wallet balance","description":"Returns balance for the specified wallet address.\n\n`confirmed` query behavior:\n- missing: defaults to confirmed view\n- `true`: confirmed view\n- `false`: unconfirmed view\n- any other value: falls back to unconfirmed view\n","parameters":[{"$ref":"#/components/parameters/AddressParam"},{"$ref":"#/components/parameters/ConfirmedQueryParamLenient"}],"responses":{"200":{"description":"Balance returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceResponse"}}}},"400":{"description":"Missing address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"AddressParam":{"name":"address","in":"path","required":true,"description":"Wallet/account address.","schema":{"type":"string","minLength":1}},"ConfirmedQueryParamLenient":{"name":"confirmed","in":"query","required":false,"description":"Balance endpoint behavior:\n- `true` for confirmed view\n- `false` for unconfirmed view\n- omitted => confirmed view\n- any other value => treated as unconfirmed view\n","schema":{"type":"string","default":"true"}}},"schemas":{"BalanceResponse":{"type":"object","required":["address","balance"],"properties":{"address":{"type":"string"},"balance":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

#### Get account details

Returns account details for an address.

## Get account details

> Returns account details (roles, keys, balances and license).\
> \
> \`confirmed\` must be exactly \`true\` or \`false\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Wallet"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/account/{address}":{"get":{"tags":["Wallet"],"summary":"Get account details","description":"Returns account details (roles, keys, balances and license).\n\n`confirmed` must be exactly `true` or `false`.\n","parameters":[{"$ref":"#/components/parameters/AddressParam"},{"$ref":"#/components/parameters/ConfirmedQueryParamStrict"}],"responses":{"200":{"description":"Account details returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountDetailsResponse"}}}},"400":{"description":"Invalid address or invalid `confirmed` parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"AddressParam":{"name":"address","in":"path","required":true,"description":"Wallet/account address.","schema":{"type":"string","minLength":1}},"ConfirmedQueryParamStrict":{"name":"confirmed","in":"query","required":false,"description":"Must be exactly `true` or `false`.","schema":{"type":"string","enum":["true","false"],"default":"true"}}},"schemas":{"AccountDetailsResponse":{"type":"object","required":["address","writingKey","isWhitelisted","isValidator","isIndexer","license","balance","stakedBalance"],"properties":{"address":{"type":"string"},"writingKey":{"description":"64-character hex writing key.\nCan be all zeros when no writer key is assigned.\n","type":"string","pattern":"^[A-Fa-f0-9]{64}$"},"isWhitelisted":{"type":"boolean"},"isValidator":{"type":"boolean"},"isIndexer":{"type":"boolean"},"license":{"type":"string","nullable":true},"balance":{"type":"string"},"stakedBalance":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

### Transactions - Read

#### List transaction hashes

Returns transaction hashes for a confirmed-length range.

{% hint style="info" %}
The start length must be less than or equal to the end length. The range must fall within the current confirmed length.
{% endhint %}

## Get transaction hashes by confirmed-length range

> Returns transaction hashes in inclusive range.\
> \
> Rules:\
> \- both params must be integers\
> \- both params must be non-negative\
> \- end must be greater than or equal to start\
> \- max difference is 1000<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Transactions"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/tx-hashes/{start_confirmed_length}/{end_confirmed_length}":{"get":{"tags":["Transactions"],"summary":"Get transaction hashes by confirmed-length range","description":"Returns transaction hashes in inclusive range.\n\nRules:\n- both params must be integers\n- both params must be non-negative\n- end must be greater than or equal to start\n- max difference is 1000\n","parameters":[{"$ref":"#/components/parameters/StartConfirmedLengthParam"},{"$ref":"#/components/parameters/EndConfirmedLengthParam"}],"responses":{"200":{"description":"Hashes returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxHashesResponse"}}}},"400":{"description":"Invalid range parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"StartConfirmedLengthParam":{"name":"start_confirmed_length","in":"path","required":true,"description":"Start of confirmed-length range (inclusive).","schema":{"type":"integer","minimum":0}},"EndConfirmedLengthParam":{"name":"end_confirmed_length","in":"path","required":true,"description":"End of confirmed-length range (inclusive).","schema":{"type":"integer","minimum":0}}},"schemas":{"TxHashesResponse":{"type":"object","required":["hashes"],"properties":{"hashes":{"type":"array","items":{"$ref":"#/components/schemas/TxHashItem"}}}},"TxHashItem":{"type":"object","required":["hash","confirmed_length"],"properties":{"hash":{"type":"string"},"confirmed_length":{"type":"integer"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

#### Get transaction by hash

Returns the transaction payload by hash.

{% hint style="info" %}
If the endpoint supports a `confirmed` query parameter, use it to select the confirmed view. Use the parameter details shown in the operation for default behavior.
{% endhint %}

## Get confirmed transaction details

> Returns normalized details for confirmed transaction hash.\
> \
> Current handler behavior:\
> \- if not found, returns \`404\` with \`{ "txDetails": null }\`\
> \- hash format is not strictly validated at handler layer<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Transactions"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/tx/{transactionHash}":{"get":{"tags":["Transactions"],"summary":"Get confirmed transaction details","description":"Returns normalized details for confirmed transaction hash.\n\nCurrent handler behavior:\n- if not found, returns `404` with `{ \"txDetails\": null }`\n- hash format is not strictly validated at handler layer\n","parameters":[{"$ref":"#/components/parameters/TransactionHashParamLoose"}],"responses":{"200":{"description":"Transaction details returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxDetailsResponse"}}}},"404":{"description":"Transaction not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxDetailsNotFoundResponse"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"parameters":{"TransactionHashParamLoose":{"name":"transactionHash","in":"path","required":true,"description":"Transaction hash.","schema":{"type":"string","minLength":1}}},"schemas":{"TxDetailsResponse":{"type":"object","required":["txDetails"],"properties":{"txDetails":{"$ref":"#/components/schemas/TxDetailsPayload"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true},"TxDetailsNotFoundResponse":{"type":"object","required":["txDetails"],"properties":{"txDetails":{"type":"object","nullable":true}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}},"responses":{"InternalServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}
```

#### Get transaction details

Returns the transaction plus decoded and enriched details.

**`txDetails.tro` example (full field set)**

Examples for `txDetails.tro` should include all fields below. This avoids “missing field” ambiguity in client code.

```json
{
  "tx": "<transaction-hash>",
  "txv": "<transaction-vailidity>",
  "to": "<to-address>",
  "am": "<amount>",
  "in": "<requester-nonce>",
  "is": "<requester-signature>",
  "va": "<validator-address>",
  "vn": "<validator-nonce>",
  "vs": "<validator-signature>"
}
```

## Get transaction details with confirmation metadata

> Returns transaction details with \`confirmed\_length\` and \`fee\`.\
> \
> \`confirmed\` must be exactly \`true\` or \`false\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Transactions"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/tx/details/{transactionHash}":{"get":{"tags":["Transactions"],"summary":"Get transaction details with confirmation metadata","description":"Returns transaction details with `confirmed_length` and `fee`.\n\n`confirmed` must be exactly `true` or `false`.\n","parameters":[{"$ref":"#/components/parameters/TransactionHashParamStrict"},{"$ref":"#/components/parameters/ConfirmedQueryParamStrict"}],"responses":{"200":{"description":"Transaction details returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxDetailsWithMetaResponse"}}}},"400":{"description":"Invalid transaction hash or invalid `confirmed` parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Transaction not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"parameters":{"TransactionHashParamStrict":{"name":"transactionHash","in":"path","required":true,"description":"Transaction hash (64-char hex string).","schema":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$"}},"ConfirmedQueryParamStrict":{"name":"confirmed","in":"query","required":false,"description":"Must be exactly `true` or `false`.","schema":{"type":"string","enum":["true","false"],"default":"true"}}},"schemas":{"TxDetailsWithMetaResponse":{"type":"object","required":["txDetails","confirmed_length","fee"],"properties":{"txDetails":{"$ref":"#/components/schemas/TxDetailsPayload"},"confirmed_length":{"type":"integer","description":"Confirmed ledger length (0 when transaction is not yet confirmed)."},"fee":{"type":"string"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}}}}
```

### Transactions - Write

#### Resolve transaction payloads (bulk)

Fetches multiple transaction payloads in one request.

{% hint style="info" %}
This endpoint enforces request and response size limits. Split requests into smaller batches when you hit limits.
{% endhint %}

## Get transaction payloads in bulk

> Returns payloads for provided transaction hash list.\
> \
> Limits:\
> \- max \`1500\` hashes per request\
> \- request body limit: \`1\_000\_000\` bytes\
> \- response body limit: \`2\_000\_000\` bytes<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Transactions"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/tx-payloads-bulk":{"post":{"tags":["Transactions"],"summary":"Get transaction payloads in bulk","description":"Returns payloads for provided transaction hash list.\n\nLimits:\n- max `1500` hashes per request\n- request body limit: `1_000_000` bytes\n- response body limit: `2_000_000` bytes\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxPayloadsBulkRequest"}}}},"responses":{"200":{"description":"Payloads returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TxPayloadsBulkResponse"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request/response size limits exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"TxPayloadsBulkRequest":{"type":"object","required":["hashes"],"properties":{"hashes":{"type":"array","minItems":1,"maxItems":1500,"items":{"type":"string"}}}},"TxPayloadsBulkResponse":{"type":"object","required":["results","missing"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TxPayloadBulkResultItem"}},"missing":{"type":"array","items":{"type":"string"}}}},"TxPayloadBulkResultItem":{"type":"object","required":["hash","payload"],"properties":{"hash":{"type":"string"},"payload":{"$ref":"#/components/schemas/TxDetailsPayload"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}}}}
```

#### Broadcast signed transaction

Broadcasts a signed transaction payload to the network.

{% hint style="warning" %}
This endpoint may return `429 Too Many Requests` when rate limited. Retry with backoff.
{% endhint %}

## Broadcast signed transaction

> Broadcasts a signed transaction payload.\
> \
> Request requirements:\
> \- body must be valid JSON\
> \- body must contain \`payload\`\
> \- \`payload\` must be valid Base64 string<br>

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"tags":[{"name":"Transactions"}],"servers":[{"url":"https://tracapi.trac.network","description":"Trac Network Mainnet"}],"paths":{"/v1/broadcast-transaction":{"post":{"tags":["Transactions"],"summary":"Broadcast signed transaction","description":"Broadcasts a signed transaction payload.\n\nRequest requirements:\n- body must be valid JSON\n- body must contain `payload`\n- `payload` must be valid Base64 string\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastTransactionRequest"}}}},"responses":{"200":{"description":"Transaction accepted and broadcasted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastTransactionResponse"}}}},"400":{"description":"Invalid request payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Broadcast retry limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"BroadcastTransactionRequest":{"type":"object","required":["payload"],"properties":{"payload":{"type":"string","description":"Base64-encoded signed transaction."}}},"BroadcastTransactionResponse":{"type":"object","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/BroadcastResult"}}},"BroadcastResult":{"type":"object","required":["message","signedLength","unsignedLength","tx"],"properties":{"message":{"type":"string"},"signedLength":{"type":"integer"},"unsignedLength":{"type":"integer"},"tx":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}}}}
```

### Errors & Limits

#### Confirmed query behavior

Some read endpoints accept a `confirmed` query parameter. It selects a confirmed view versus an unconfirmed view. Treat it as a consistency knob for reads.

#### `tx-hashes` range constraints

Ranges are constrained by confirmed length. Invalid ranges should be treated as client errors. Request smaller windows if you hit server limits.

#### Bulk request limits

`/v1/tx-payloads-bulk` is designed for batching. Keep batches small and bounded.

#### Broadcast rate limiting

`/v1/broadcast-transaction` can respond with `429`. Back off and retry.

### Schemas

## The TxDetailsWithMetaResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxDetailsWithMetaResponse":{"type":"object","required":["txDetails","confirmed_length","fee"],"properties":{"txDetails":{"$ref":"#/components/schemas/TxDetailsPayload"},"confirmed_length":{"type":"integer","description":"Confirmed ledger length (0 when transaction is not yet confirmed)."},"fee":{"type":"string"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true}}}}
```

## The TxPayloadsBulkResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxPayloadsBulkResponse":{"type":"object","required":["results","missing"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TxPayloadBulkResultItem"}},"missing":{"type":"array","items":{"type":"string"}}}},"TxPayloadBulkResultItem":{"type":"object","required":["hash","payload"],"properties":{"hash":{"type":"string"},"payload":{"$ref":"#/components/schemas/TxDetailsPayload"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true}}}}
```

## The TxPayloadBulkResultItem object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxPayloadBulkResultItem":{"type":"object","required":["hash","payload"],"properties":{"hash":{"type":"string"},"payload":{"$ref":"#/components/schemas/TxDetailsPayload"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true}}}}
```

## The TxPayloadsBulkRequest object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxPayloadsBulkRequest":{"type":"object","required":["hashes"],"properties":{"hashes":{"type":"array","minItems":1,"maxItems":1500,"items":{"type":"string"}}}}}}}
```

## The TxDetailsNotFoundResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxDetailsNotFoundResponse":{"type":"object","required":["txDetails"],"properties":{"txDetails":{"type":"object","nullable":true}}}}}}
```

## The TxDetailsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxDetailsResponse":{"type":"object","required":["txDetails"],"properties":{"txDetails":{"$ref":"#/components/schemas/TxDetailsPayload"}}},"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true}}}}
```

## The TxDetailsPayload object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxDetailsPayload":{"type":"object","description":"Normalized transaction payload.","required":["type","address"],"properties":{"type":{"type":"integer"},"address":{"type":"string"},"tro":{"$ref":"#/components/schemas/TxOperationPayload"},"txo":{"$ref":"#/components/schemas/TxOperationPayload"}},"oneOf":[{"required":["tro"]},{"required":["txo"]}],"additionalProperties":false},"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true}}}}
```

## The TxOperationPayload object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxOperationPayload":{"type":"object","description":"Normalized operation object (`tro` for transfer or `txo` for subnet tx).\nFields depend on operation type; unknown keys may also appear.\n","properties":{"tx":{"type":"string","description":"Transaction hash."},"txv":{"type":"string","description":"Transaction validity hash."},"to":{"type":"string","description":"Recipient address (transfer)."},"am":{"type":"string","description":"Amount in base units."},"in":{"type":"string","description":"Nonce."},"is":{"type":"string","description":"Signature."},"va":{"type":"string","description":"Validator address or encoded validator field."},"vn":{"type":"string","description":"Validator nonce or validator-related field."},"vs":{"type":"string","description":"Validator signature or validator-related field."},"iw":{"type":"string","description":"Writer/indexer related field."},"bs":{"type":"string","description":"Bootstrap/subnetwork identifier (for subnet tx)."}},"additionalProperties":true}}}}
```

## The TxHashesResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxHashesResponse":{"type":"object","required":["hashes"],"properties":{"hashes":{"type":"array","items":{"$ref":"#/components/schemas/TxHashItem"}}}},"TxHashItem":{"type":"object","required":["hash","confirmed_length"],"properties":{"hash":{"type":"string"},"confirmed_length":{"type":"integer"}}}}}}
```

## The TxHashItem object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxHashItem":{"type":"object","required":["hash","confirmed_length"],"properties":{"hash":{"type":"string"},"confirmed_length":{"type":"integer"}}}}}}
```

## The BroadcastTransactionResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"BroadcastTransactionResponse":{"type":"object","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/BroadcastResult"}}},"BroadcastResult":{"type":"object","required":["message","signedLength","unsignedLength","tx"],"properties":{"message":{"type":"string"},"signedLength":{"type":"integer"},"unsignedLength":{"type":"integer"},"tx":{"type":"string"}}}}}}
```

## The BroadcastResult object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"BroadcastResult":{"type":"object","required":["message","signedLength","unsignedLength","tx"],"properties":{"message":{"type":"string"},"signedLength":{"type":"integer"},"unsignedLength":{"type":"integer"},"tx":{"type":"string"}}}}}}
```

## The BroadcastTransactionRequest object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"BroadcastTransactionRequest":{"type":"object","required":["payload"],"properties":{"payload":{"type":"string","description":"Base64-encoded signed transaction."}}}}}}
```

## The UnconfirmedLengthResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"UnconfirmedLengthResponse":{"type":"object","required":["unconfirmed_length"],"properties":{"unconfirmed_length":{"type":"integer"}}}}}}
```

## The ConfirmedLengthResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"ConfirmedLengthResponse":{"type":"object","required":["confirmed_length"],"properties":{"confirmed_length":{"type":"integer"}}}}}}
```

## The FeeResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"FeeResponse":{"type":"object","required":["fee"],"properties":{"fee":{"type":"string"}}}}}}
```

## The TxvResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"TxvResponse":{"type":"object","required":["txv"],"properties":{"txv":{"type":"string"}}}}}}
```

## The AccountDetailsResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"AccountDetailsResponse":{"type":"object","required":["address","writingKey","isWhitelisted","isValidator","isIndexer","license","balance","stakedBalance"],"properties":{"address":{"type":"string"},"writingKey":{"description":"64-character hex writing key.\nCan be all zeros when no writer key is assigned.\n","type":"string","pattern":"^[A-Fa-f0-9]{64}$"},"isWhitelisted":{"type":"boolean"},"isValidator":{"type":"boolean"},"isIndexer":{"type":"boolean"},"license":{"type":"string","nullable":true},"balance":{"type":"string"},"stakedBalance":{"type":"string"}}}}}}
```

## The BalanceResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"BalanceResponse":{"type":"object","required":["address","balance"],"properties":{"address":{"type":"string"},"balance":{"type":"string"}}}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.0.3","info":{"title":"Trac Network RPC API","version":"1.0.2"},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Error message describing the failure."}}}}}}
```