IOTA chains API
The chains API from IOTA — 18 operation(s) for chains.
OpenAPI Specification
openapi: 3.0.1
info:
description: REST API for the Wasp node
title: Wasp auth chains API
version: '0'
servers:
- url: /
tags:
- name: chains
paths:
/v1/chain:
get:
operationId: getChainInfo
parameters:
- description: Block index or trie root
in: query
name: block
schema:
format: string
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChainInfoResponse'
description: Information about a specific chain
summary: Get information about a specific chain
tags:
- chains
/v1/chain/access-node/{peer}:
delete:
operationId: removeAccessNode
parameters:
- description: Name or PubKey (hex) of the trusted peer
in: path
name: peer
required: true
schema:
format: string
type: string
responses:
'200':
content: {}
description: Access node was successfully removed
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Remove an access node.
tags:
- chains
put:
operationId: addAccessNode
parameters:
- description: Name or PubKey (hex) of the trusted peer
in: path
name: peer
required: true
schema:
format: string
type: string
responses:
'201':
content: {}
description: Access node was successfully added
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Configure a trusted node to be an access node.
tags:
- chains
/v1/chain/activate/{chainID}:
post:
operationId: activateChain
parameters:
- description: ChainID (Hex Address)
in: path
name: chainID
required: true
schema:
format: string
type: string
responses:
'200':
content: {}
description: Chain was successfully activated
'304':
content: {}
description: Chain was not activated
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Activate a chain
tags:
- chains
/v1/chain/callview:
post:
description: Execute a view call. Either use HName or Name properties. If both are supplied, HName are used.
operationId: callView
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContractCallViewRequest'
description: Parameters
required: true
responses:
'200':
content:
application/json:
schema:
items:
example: 171
format: string
type: string
type: array
description: Result
summary: Call a view function on a contract by Hname
tags:
- chains
x-codegen-request-body-name: ''
/v1/chain/chainrecord/{chainID}:
post:
operationId: setChainRecord
parameters:
- description: ChainID (Hex Address)
in: path
name: chainID
required: true
schema:
format: string
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ChainRecord'
description: Chain Record
required: true
responses:
'201':
content: {}
description: Chain record was saved
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Sets the chain record.
tags:
- chains
x-codegen-request-body-name: ChainRecord
/v1/chain/committee:
get:
operationId: getCommitteeInfo
parameters:
- description: Block index or trie root
in: query
name: block
schema:
format: string
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CommitteeInfoResponse'
description: A list of all nodes tied to the chain
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Get information about the deployed committee
tags:
- chains
/v1/chain/contracts:
get:
operationId: getContracts
parameters:
- description: Block index or trie root
in: query
name: block
schema:
format: string
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ContractInfoResponse'
type: array
description: A list of all available contracts
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Get all available chain contracts
tags:
- chains
/v1/chain/deactivate:
post:
operationId: deactivateChain
responses:
'200':
content: {}
description: Chain was successfully deactivated
'304':
content: {}
description: Chain was not deactivated
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Deactivate a chain
tags:
- chains
/v1/chain/dump-accounts:
post:
operationId: dump-accounts
responses:
'200':
content: {}
description: Accounts dump will be produced
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: dump accounts information into a humanly-readable format
tags:
- chains
/v1/chain/estimategas-offledger:
post:
operationId: estimateGasOffledger
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EstimateGasRequestOffledger'
description: Request
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptResponse'
description: ReceiptResponse
summary: Estimates gas for a given off-ledger ISC request
tags:
- chains
x-codegen-request-body-name: Request
/v1/chain/estimategas-onledger:
post:
description: Estimates gas usage for a given on-ledger ISC request. To calculate required L1 and L2 gas budgets use values of L1.GasBudget and L2.GasBurned respectively.
operationId: estimateGasOnledger
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EstimateGasRequestOnledger'
description: Request
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/OnLedgerEstimationResponse'
description: ReceiptResponse
summary: Estimates gas for a given on-ledger ISC request
tags:
- chains
x-codegen-request-body-name: Request
/v1/chain/evm:
post:
responses:
default:
content: {}
description: successful operation
summary: Ethereum JSON-RPC
tags:
- chains
/v1/chain/evm/ws:
get:
responses:
default:
content: {}
description: successful operation
summary: Ethereum JSON-RPC (Websocket transport)
tags:
- chains
/v1/chain/mempool:
get:
operationId: getMempoolContents
responses:
'200':
content:
application/octet-stream:
schema:
items:
format: int32
type: integer
type: array
description: stream of JSON representation of the requests in the mempool
'401':
content:
application/octet-stream:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Get the contents of the mempool.
tags:
- chains
/v1/chain/receipts/{requestID}:
get:
operationId: getReceipt
parameters:
- description: RequestID (Hex)
in: path
name: requestID
required: true
schema:
format: string
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptResponse'
description: ReceiptResponse
'404':
content: {}
description: Chain or request id not found
summary: Get a receipt from a request ID
tags:
- chains
/v1/chain/requests/{requestID}/wait:
get:
operationId: waitForRequest
parameters:
- description: RequestID (Hex)
in: path
name: requestID
required: true
schema:
format: string
type: string
- description: The timeout in seconds, maximum 60s
in: query
name: timeoutSeconds
schema:
format: int32
type: integer
- description: Wait for the block to be confirmed on L1
in: query
name: waitForL1Confirmation
schema:
format: boolean
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptResponse'
description: The request receipt
'404':
content: {}
description: The chain or request id not found
'408':
content: {}
description: The waiting time has reached the defined limit
summary: Wait until the given request has been processed by the node
tags:
- chains
/v1/chain/rotate:
post:
operationId: rotateChain
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RotateChainRequest'
description: RotateRequest
required: false
responses:
'200':
content: {}
description: Chain rotation was requested
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
description: Unauthorized (Wrong permissions, missing token)
security:
- Authorization: []
summary: Rotate a chain
tags:
- chains
x-codegen-request-body-name: RotateRequest
/v1/chain/state/{stateKey}:
get:
operationId: getStateValue
parameters:
- description: State Key (Hex)
in: path
name: stateKey
required: true
schema:
format: string
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StateResponse'
description: Result
summary: Fetch the raw value associated with the given key in the chain state
tags:
- chains
components:
schemas:
ValidationError:
example:
error: error
missingPermission: missingPermission
properties:
error:
format: string
type: string
xml:
name: Error
missingPermission:
format: string
type: string
xml:
name: MissingPermission
required:
- error
- missingPermission
type: object
xml:
name: ValidationError
ChainRecord:
example:
accessNodes:
- accessNodes
- accessNodes
isActive: true
properties:
accessNodes:
items:
format: string
type: string
type: array
xml:
name: AccessNodes
wrapped: true
isActive:
format: boolean
type: boolean
xml:
name: IsActive
required:
- accessNodes
- isActive
type: object
xml:
name: ChainRecord
CoinJSON:
example:
coinType: coinType
balance: balance
properties:
balance:
description: The balance (uint64 as string)
format: string
type: string
xml:
name: Balance
coinType:
format: string
type: string
xml:
name: CoinType
required:
- balance
- coinType
type: object
xml:
name: CoinJSON
Limits:
example:
maxGasExternalViewCall: 5
minGasPerRequest: 9
maxGasPerBlock: 2
maxGasPerRequest: 7
properties:
maxGasExternalViewCall:
description: The maximum gas per external view call
format: int64
type: integer
xml:
name: MaxGasExternalViewCall
maxGasPerBlock:
description: The maximum gas per block
format: int64
type: integer
xml:
name: MaxGasPerBlock
maxGasPerRequest:
description: The maximum gas per request
format: int64
type: integer
xml:
name: MaxGasPerRequest
minGasPerRequest:
description: The minimum gas per request
format: int64
type: integer
xml:
name: MinGasPerRequest
required:
- maxGasExternalViewCall
- maxGasPerBlock
- maxGasPerRequest
- minGasPerRequest
type: object
xml:
name: Limits
EstimateGasRequestOnledger:
example:
transactionBytes: transactionBytes
properties:
transactionBytes:
description: Hexadecimal bytes of transaction to estimate
format: string
type: string
xml:
name: TransactionBytes
required:
- transactionBytes
type: object
xml:
name: EstimateGasRequestOnledger
ReceiptResponse:
example:
gasBurnLog:
- code: 6
gasBurned: 1
- code: 6
gasBurned: 1
request:
senderAccount: senderAccount
allowanceError: allowanceError
assets:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balance
objects:
- id: id
type: type
- id: id
type: type
isOffLedger: true
requestId: requestId
callTarget:
contractHName: contractHName
functionHName: functionHName
gasBudget: gasBudget
allowance:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balance
objects:
- id: id
type: type
- id: id
type: type
params:
- params
- params
isEVM: true
blockIndex: 1
rawError:
code: code
params:
- params
- params
requestIndex: 1
storageDepositCharged: storageDepositCharged
gasFeeCharged: gasFeeCharged
errorMessage: errorMessage
gasBudget: gasBudget
gasBurned: gasBurned
properties:
blockIndex:
format: int32
minimum: 1
type: integer
xml:
name: BlockIndex
errorMessage:
format: string
type: string
xml:
name: ErrorMessage
gasBudget:
description: The gas budget (uint64 as string)
format: string
type: string
xml:
name: GasBudget
gasBurnLog:
items:
$ref: '#/components/schemas/BurnRecord'
type: array
xml:
name: GasBurnLog
wrapped: true
gasBurned:
description: The burned gas (uint64 as string)
format: string
type: string
xml:
name: GasBurned
gasFeeCharged:
description: The charged gas fee (uint64 as string)
format: string
type: string
xml:
name: GasFeeCharged
rawError:
$ref: '#/components/schemas/UnresolvedVMErrorJSON'
request:
$ref: '#/components/schemas/RequestJSON'
requestIndex:
format: int32
minimum: 1
type: integer
xml:
name: RequestIndex
storageDepositCharged:
description: Storage deposit charged (uint64 as string)
format: string
type: string
xml:
name: SDCharged
required:
- blockIndex
- gasBudget
- gasBurnLog
- gasBurned
- gasFeeCharged
- request
- requestIndex
- storageDepositCharged
type: object
xml:
name: ReceiptResponse
RequestJSON:
example:
senderAccount: senderAccount
allowanceError: allowanceError
assets:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balance
objects:
- id: id
type: type
- id: id
type: type
isOffLedger: true
requestId: requestId
callTarget:
contractHName: contractHName
functionHName: functionHName
gasBudget: gasBudget
allowance:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balance
objects:
- id: id
type: type
- id: id
type: type
params:
- params
- params
isEVM: true
properties:
allowance:
$ref: '#/components/schemas/AssetsJSON'
allowanceError:
format: string
type: string
xml:
name: AllowanceError
assets:
$ref: '#/components/schemas/AssetsJSON'
callTarget:
$ref: '#/components/schemas/CallTargetJSON'
gasBudget:
description: The gas budget (uint64 as string)
format: string
type: string
xml:
name: GasBudget
isEVM:
format: boolean
type: boolean
xml:
name: IsEVM
isOffLedger:
format: boolean
type: boolean
xml:
name: IsOffLedger
params:
items:
format: string
type: string
type: array
xml:
name: Params
wrapped: true
requestId:
format: string
type: string
xml:
name: RequestID
senderAccount:
format: string
type: string
xml:
name: SenderAccount
required:
- allowance
- assets
- callTarget
- gasBudget
- isEVM
- isOffLedger
- params
- requestId
- senderAccount
type: object
xml:
name: RequestJSON
EstimateGasRequestOffledger:
example:
requestBytes: requestBytes
fromAddress: fromAddress
properties:
fromAddress:
description: The address to estimate gas for(Hex)
format: string
type: string
xml:
name: FromAddress
requestBytes:
description: Offledger Request (Hex)
format: string
type: string
xml:
name: Request
required:
- fromAddress
- requestBytes
type: object
xml:
name: EstimateGasRequestOffledger
FeePolicy:
example:
gasPerToken:
a: 0
b: 0
validatorFeeShare: 5
evmGasRatio:
a: 0
b: 0
properties:
evmGasRatio:
$ref: '#/components/schemas/Ratio32'
gasPerToken:
$ref: '#/components/schemas/Ratio32'
validatorFeeShare:
description: The validator fee share.
format: int32
type: integer
xml:
name: ValidatorFeeShare
required:
- evmGasRatio
- gasPerToken
- validatorFeeShare
type: object
xml:
name: FeePolicy
Ratio32:
example:
a: 0
b: 0
properties:
a:
format: int32
minimum: 0
type: integer
xml:
name: A
b:
format: int32
minimum: 0
type: integer
xml:
name: B
required:
- a
- b
type: object
xml:
name: Ratio32
PeeringNodeStatusResponse:
example:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
properties:
isAlive:
description: Whether or not the peer is activated
format: boolean
type: boolean
xml:
name: IsAlive
isTrusted:
format: boolean
type: boolean
xml:
name: IsTrusted
name:
format: string
type: string
xml:
name: Name
numUsers:
description: The amount of users attached to the peer
format: int32
type: integer
xml:
name: NumUsers
peeringURL:
description: The peering URL of the peer
format: string
type: string
xml:
name: PeeringURL
publicKey:
description: The peers public key encoded in Hex
format: string
type: string
xml:
name: PublicKey
required:
- isAlive
- isTrusted
- name
- numUsers
- peeringURL
- publicKey
type: object
xml:
name: PeeringNodeStatusResponse
UnresolvedVMErrorJSON:
example:
code: code
params:
- params
- params
properties:
code:
format: string
type: string
xml:
name: ErrorCode
params:
items:
format: string
type: string
type: array
xml:
name: Params
wrapped: true
type: object
xml:
name: UnresolvedVMErrorJSON
ContractInfoResponse:
example:
name: name
hName: hName
properties:
hName:
description: The id (HName as Hex)) of the contract.
format: string
type: string
xml:
name: HName
name:
description: The name of the contract.
format: string
type: string
xml:
name: Name
required:
- hName
- name
type: object
xml:
name: ContractInfoResponse
CallTargetJSON:
example:
contractHName: contractHName
functionHName: functionHName
properties:
contractHName:
description: The contract name as HName (Hex)
format: string
type: string
xml:
name: ContractHName
functionHName:
description: The function name as HName (Hex)
format: string
type: string
xml:
name: FunctionHName
required:
- contractHName
- functionHName
type: object
xml:
name: CallTargetJSON
OnLedgerEstimationResponse:
example:
l1:
storageRebate: storageRebate
storageFee: storageFee
computationFee: computationFee
gasFeeCharged: gasFeeCharged
gasBudget: gasBudget
l2:
gasBurnLog:
- code: 6
gasBurned: 1
- code: 6
gasBurned: 1
request:
senderAccount: senderAccount
allowanceError: allowanceError
assets:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balance
objects:
- id: id
type: type
- id: id
type: type
isOffLedger: true
requestId: requestId
callTarget:
contractHName: contractHName
functionHName: functionHName
gasBudget: gasBudget
allowance:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balance
objects:
- id: id
type: type
- id: id
type: type
params:
- params
- params
isEVM: true
blockIndex: 1
rawError:
code: code
params:
- params
- params
requestIndex: 1
storageDepositCharged: storageDepositCharged
gasFeeCharged: gasFeeCharged
errorMessage: errorMessage
gasBudget: gasBudget
gasBurned: gasBurned
properties:
l1:
$ref: '#/components/schemas/L1EstimationResult'
l2:
$ref: '#/components/schemas/ReceiptResponse'
required:
- l1
- l2
type: object
xml:
name: OnLedgerEstimationResponse
ChainInfoResponse:
example:
chainAdmin: chainAdmin
metadata:
website: website
evmWebSocketURL: evmWebSocketURL
name: name
description: description
evmJsonRpcURL: evmJsonRpcURL
gasLimits:
maxGasExternalViewCall: 5
minGasPerRequest: 9
maxGasPerBlock: 2
maxGasPerRequest: 7
chainID: chainID
evmChainId: 1
publicURL: publicURL
gasFeePolicy:
gasPerToken:
a: 0
b: 0
validatorFeeShare: 5
evmGasRatio:
a: 0
b: 0
isActive: true
properties:
chainAdmin:
description: The chain admin address (Hex Address)
format: string
type: string
xml:
name: ChainAdmin
chainID:
description: ChainID (Hex Address)
format: string
type: string
xml:
name: ChainID
evmChainId:
description: The EVM chain ID
format: int32
minimum: 1
type: integer
xml:
name: EVMChainID
gasFeePolicy:
$ref: '#/components/schemas/FeePolicy'
gasLimits:
$ref: '#/components/schemas/Limits'
isActive:
description: Whether or not the chain is active
format: boolean
type: boolean
xml:
name: IsActive
metadata:
$ref: '#/components/schemas/PublicChainMetadata'
publicURL:
description: The fully qualified public url leading to the chains metadata
format: string
type: string
xml:
name: PublicURL
required:
- chainAdmin
- chainID
- evmChainId
- gasFeePolicy
- gasLimits
- isActive
- metadata
- publicURL
type: object
xml:
name: ChainInfoResponse
CommitteeInfoResponse:
example:
candidateNodes:
- node:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
accessAPI: accessAPI
- node:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
accessAPI: accessAPI
committeeNodes:
- node:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
accessAPI: accessAPI
- node:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
accessAPI: accessAPI
chainId: chainId
accessNodes:
- node:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
accessAPI: accessAPI
- node:
isAlive: true
peeringURL: peeringURL
name: name
publicKey: publicKey
numUsers: 0
isTrusted: true
accessAPI: accessAPI
stateAddress: stateAddress
active: true
properties:
accessNodes:
description: A list of all access nodes and their peering info.
items:
$ref: '#/components/schemas/CommitteeNode'
type: array
xml:
name: AccessNodes
wrapped: true
active:
description: Whether or not the chain is active.
format: boolean
type: boolean
xml:
name: Active
candidateNodes:
description: A list of all candidate nodes and their peering info.
items:
$ref: '#/components/schemas/CommitteeNode'
type: array
xml:
name: CandidateNodes
wrapped: true
chainId:
description: ChainID (Hex Address).
format: string
type: string
xml:
name: ChainID
committeeNodes:
description: A list of all committee nodes and their peering info.
items:
$ref: '#/components/schemas/CommitteeNode'
type: array
xml:
name: CommitteeNodes
wrapped: true
stateAddress:
format: string
type: string
xml:
name: StateAddress
required:
- accessNodes
- active
- candidateNodes
- chainId
- committeeNodes
- stateAddress
type: object
xml:
name: CommitteeInfoResponse
AssetsJSON:
example:
coins:
- coinType: coinType
balance: balance
- coinType: coinType
balance: balanc
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/iota/refs/heads/main/openapi/iota-chains-api-openapi.yml