Python API Reference
The source code is found on GitHub at https://github.com/icon-project/icon-sdk-python

Querying API Methods

Examples

1
from iconsdk.builder.call_builder import CallBuilder
2
​
3
# Returns block information by block height
4
block = icon_service.get_block(1000)
5
​
6
# Returns block information by block hash
7
block = icon_service.get_block("0x000...000")
8
​
9
# Returns the last block information
10
block = icon_service.get_block("latest")
11
​
12
# Returns the balance of the account of given address
13
balance = icon_service.get_balance("hx000...1")
14
​
15
# Returns a list of the SCORE APIs
16
score_apis = icon_service.get_score_api("cx000...1")
17
​
18
# Returns the total supply of ICX
19
total_supply = icon_service.get_total_supply()
20
​
21
# Returns information about a transaction requested by transaction hash
22
tx = icon_service.get_transaction("0x000...000")
23
​
24
# Returns the result of a transaction by transaction hash
25
tx_result = icon_service.get_transaction_result("0x000...000")
26
​
27
# Generates a call instance using the CallBuilder
28
call = CallBuilder().from_(wallet.get_address())\
29
.to("cx000...1")\
30
.method("balance_of")\
31
.params({"address": "hx000...1"})\
32
.build()
33
​
34
# Executes a call method to call a read-only API method on the SCORE immediately without creating a transaction on Loopchain
35
result = icon_service.call(call)

Error Cases

There are different types of error cases as below. The exception is raised with the specific message. You can get more information about the exception from the message.
    KeyStoreException
      It is raised when making or loading a key store file.
      Error code for the exception is 1.
    AddressException
      It is raised when the address is invalid.
      Error code for the exception is 2.
    BalanceException
      It is raised when the balance is invalid.
      Error code for the exception is 3.
    DataTypeException
      It is raised when the data type is invalid.
      Error code for the exception is 4.
    JSONRPCException
      It is raised when JSON-RPC response is an error.
      Error code for the exception is 5.
    ZipException
      It is raised while writing zip in memory.
      Error code for the exception is 6.

get_block

1
get_block(value)
    Function A
      Returns block information by block height
      Delegates to icx_getBlockByHeight RPC method
    Function B
      Returns block information by block hash
      Delegates to icx_getBlockByHash RPC method
    Function C
      Returns the last block information
      Delegates to icx_getLastBlock RPC method
Parameters
    Function A
      value : Integer of a block height
    Function B
      value : Hash of a block prefixed with '0x'
    Function C
      value : 'latest'
Returns
Block data
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Returns block information by block height
2
block = icon_service.get_block(1000)
3
​
4
# Returns block information by block hash
5
block = icon_service.get_block("0x000...000")
6
​
7
# Returns the last block information
8
block = icon_service.get_block("latest")

get_balance

1
get_balance(address: str)
Returns the ICX balance of the given EOA or SCORE
Delegates to icx_getBalance RPC method
Parameters
address : An address of EOA or SCORE
Returns
Number of ICX coins
Error Cases
    AddressException : Address is invalid.
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Returns the ICX balance of the given EOA or SCORE
2
balance = icon_service.get_balance("hx000...1")

get_score_api

1
get_score_api(address: str)
Returns SCORE's external API list
Delegates to icx_getScoreApi RPC method
Parameters
address : A SCORE address to be examined
Returns
A list of API methods of the SCORE and its information
Fields :
    type : Method type; function, fallback, or eventlog
    name : Function name on the SCORE
    inputs : A list of information of parameters
      name : Parameter name
      type : Parameter type ; int, str, bytes, bool, Address
      indexed : In the case of eventlog, tells if the parameter is indexed.
    outputs : Return value
      type : Return value type ; int, str, bytes, bool, Address
    Readonly : External (readonly=True)
    Payable: Payable
Error Cases
    AddressException : Address is invalid.
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Returns SCORE's external API list
2
score_apis = icon_service.get_score_api("cx000...1")

get_total_supply

1
get_total_supply()
Returns total ICX coin supply that has been issued
Delegates to icx_getTotalSupply RPC method
Parameters
None
Returns
Total number of ICX coins issued
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Returns total ICX coin supply that has been issued
2
total_supply = icon_service.get_total_supply()

get_transaction

1
get_transaction(tx_hash: str)
Returns the transaction information requested by transaction hash
Delegates to icx_getTransactionByHash RPC method
Parameters
tx_hash : Transaction hash prefixed with '0x'
Returns
Information about a transaction
Fields :
    version : Protocol version (3 for V3)
    from : An EOA address that created the transaction
    to : An EOA address to receive coins, or SCORE address to execute the transaction
    value : Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 10 ^ 18 loop)
    stepLimit : Maximum step allowance that can be used by the transaction
    timestamp : Transaction creation time. Timestamp is in microseconds.
    nid : Network ID (1 for Main net, etc)
    nonce : An arbitrary number used to prevent transaction hash collision
    txHash : Transaction hash
    txIndex : Transaction index in a block. Null when it is pending.
    blockHeight : Block height including the transaction. Null when it is pending
    blockHash : Block hash including the transaction. Null when it is pending.
    signature : Signature of the transaction
    dataType : Data type; call, deploy, message
    data : Contains various type of data depending on the dataType
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Returns the transaction information requested by transaction hash
2
tx = icon_service.get_transaction("0x000...000")

get_transaction_result

1
get_transaction_result(tx_hash: str)
Returns the transaction result requested by transaction hash
Delegates to icx_getTransactionResult RPC method
Parameters
tx_hash : Hash of a transaction prefixed with '0x'
Returns
A transaction result object
Field :
    status : 1 on success, 0 on failure
    to : Recipient address of the transaction
    failure : This field exists when status is 0. Contains code(str) and message(str)
    txHash : Transaction hash
    txIndex : Transaction index in the block
    blockHeight : Block height including the transaction
    blockHash : Block hash including the transaction
    cumulativeStepUsed : Sum of stepUsed by this transaction and all preceding transactions in the same block
    stepUsed : The amount of step used by this transaction
    stepPrice: The step price used by this transaction
    scoreAddress : A SCORE address if the transaction created a new SCORE. (optional)
    eventLogs : Array of eventlogs generated by this transaction
    logsBloom : Bloom filter to quickly retrieve related eventlogs
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Returns the transaction result requested by transaction hash
2
tx_result = icon_service.get_transaction_result("0x000...000")

call

1
call(call: Call)
Calls SCORE's external function which is read-only without creating a transaction on Loopchain
Delegates to icx_call RPC method
Parameters
Call object made by CallBuilder
Fields :
    from : Message sender's address
    to : A SCORE address that will handle the message
    method : name of an external function
    params : Parameters to be passed to the function (optional). A data type of params should be dict.
Returns
Values returned by the executed SCORE function
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Generates a call instance using the CallBuilder
2
call = CallBuilder().from_(wallet.get_address())\
3
.to("cx000...1")\
4
.method("balance_of")\
5
.params({"address": "hx000...1"})\
6
.build()
7
​
8
# Calls SCORE's external function which is read-only without creating a transaction on Loopchain
9
result = icon_service.call(call)

Loading a Wallet and Storing the Keystore

To send transactions, first, you should make an instance of your wallet.
You can make an instance of the wallet using bytes of the private key or from a keystore file.

Examples

1
from iconsdk.wallet.wallet import KeyWallet
2
​
3
# Generates a wallet
4
wallet = KeyWallet.create()
5
​
6
# Loads a wallet from bytes of the private key
7
wallet = KeyWallet.load(b'-B\x99...xedy')
8
​
9
# Loads a wallet from a keystore file
10
wallet = KeyWallet.load("./keystore", "password")
11
​
12
# Stores a keystore file on the file path
13
wallet.store("./keystore", "password") # throw exception if having an error.
14
​
15
# Returns an Address
16
wallet.get_address()
17
​
18
# Returns a private key
19
wallet.get_private_key()
20
​
21
# Signs the transaction
22
signature = wallet.sign(b'D8\xe9...\xfc')

API Methods of KeyWallet

create

1
create()
Generates an instance of Wallet without a specific private key
Parameters
None
Returns
An instance of Wallet class
Example
1
# Generates a wallet
2
wallet = KeyWallet.create()

load

1
load(private_key: bytes)
Loads a wallet from bytes of the private key and generates an instance of Wallet
Parameters
private_key : Bytes of the private key
Returns
An instance of Wallet class
Error Cases
    DataTypeException : Private key is invalid.
Example
1
# Loads a wallet from a private key in bytes
2
wallet = KeyWallet.load(b'-B\x99...xedy')

load

1
load(file_path, password)
Loads a wallet from a keystore file with your password and generates an instance of Wallet
Parameters
    file_path : File path of the keystore file
    password : Password for the keystore file. Password must include alphabet character, number, and special character
Returns
An instance of Wallet class
Error Cases
    KeyStoreException: Key store file is invalid.
Example
1
# Loads a wallet from a keystore file
2
wallet = KeyWallet.load("./keystore", "password")

store

1
store(file_path, password)
Stores data of an instance of a derived wallet class on the file path with your password
Parameters
    file_path : File path of the keystore file
    password : Password for the keystore file. Password must include alphabet character, number, and special character
Returns
None
Error Cases
    KeyStoreException: Key store file is invalid.
Example
1
# Stores a keystore file on the file path
2
wallet.store("./keystore", "password") # throw exception if having an error.

get_address

1
get_address()
Returns an EOA address
The format of your account (which is generated from your public key) is hxfd7e4560ba363f5aabd32caac7317feeee70ea57.
Parameters
None
Returns
An EOA address
Example
1
# Returns an EOA address
2
wallet.get_address()

get_private_key

1
get_private_key()
Returns hex string of the private key of the wallet
Parameters
None
Returns
Hex string of the private key
Example
1
# Returns the private key
2
wallet.get_private_key()

sign

1
sign(data: bytes)
Returns bytes of the ECDSA-SHA256 signature made from the data
Parameters
data : bytes of the transaction
Returns
Bytes of the signature
Error Cases
    DataTypeException : Data type is invalid.
Example
1
# Signs the transaction
2
signature = wallet.sign(b'D8\xe9...\xfc')

Signing and Sending Transaction

Generating a Transaction

After then, you should create an instance of the transaction using different types of transaction builders as follows.

Signing a Transaction

Before sending a transaction, the transaction should be signed by using SignedTransaction class. The SignedTransaction class is used to sign the transaction by returning an instance of the signed transaction as demonstrated in the example below. The instance of the signed transaction has the property of a signature.

Sending a Transaction

Finally, you can send a transaction with the signed transaction object as follows.

Examples

1
from iconsdk.builder.transaction_builder import (
2
TransactionBuilder,
3
DeployTransactionBuilder,
4
CallTransactionBuilder,
5
MessageTransactionBuilder
6
)
7
from iconsdk.signed_transaction import SignedTransaction
8
​
9
# Generates an instance of transaction for sending icx.
10
transaction = TransactionBuilder()\
11
.from_(wallet.get_address())\
12
.to("cx00...02")\
13
.value(150000000)\
14
.step_limit(1000000)\
15
.nid(3)\
16
.nonce(100)\
17
.build()
18
​
19
# Generates an instance of transaction for deploying SCORE.
20
transaction = DeployTransactionBuilder()\
21
.from_(wallet.get_address())\
22
.to("cx00...02")\
23
.step_limit(1000000)\
24
.nid(3)\
25
.nonce(100)\
26
.content_type("application/zip")\
27
.content(b'D8\xe9...\xfc')\
28
.params(params)\
29
.build()
30
​
31
# Generates an instance of transaction for the calling method in SCORE.
32
transaction = CallTransactionBuilder()\
33
.from_(wallet.get_address())\
34
.to("cx00...02")\
35
.step_limit(1000000)\
36
.nid(3)\
37
.nonce(100)\
38
.method("transfer")\
39
.params(params)\
40
.build()
41
​
42
# Generates an instance of transaction for sending a message.
43
transaction = MessageTransactionBuilder()\
44
.from_(wallet.get_address())\
45
.to("cx00...02")\
46
.step_limit(1000000)\
47
.nid(3)\
48
.nonce(100)\
49
.data("test")\
50
.build()
51
​
52
# Returns the signed transaction object having a signature
53
signed_transaction = SignedTransaction(transaction, wallet)
54
​
55
# Sends the transaction
56
tx_hash = icon_service.send_transaction(signed_transaction)

TransactionBuilder

Builder for a Transaction object
Methods
    from_ : The wallet address making a transaction. The default address is your account address.
    to : The wallet address to receive coin or SCORE address to receive a transaction.
    value : The amount of ICX to be sent. (Optional)
    step_limit : The maximum step value for processing a transaction.
    nid : Network ID. Default nid is 1 if you didn't set the value. (1 for Main net, etc)
    nonce : An arbitrary number used to prevent transaction hash collision. (Optional)
    version : Protocol version (3 for V3). The default version is 3 if you didn't set the value.
    timestamp : Transaction creation time. Timestamp is in microseconds. Default timestamp is set, if you didn't set the value.
    build : Returns an ICX transaction object
Returns
A transaction object
Example
1
# Generates an instance of transaction for sending icx.
2
transaction = TransactionBuilder()\
3
.from_(wallet.get_address())\
4
.to("cx00...02")\
5
.value(150000000)\
6
.step_limit(1000000)\
7
.nid(3)\
8
.nonce(100)\
9
.build()

DeployTransactionBuilder

Builder for DeployTransaction object
Methods
    from_ : The wallet address making a transaction. The default address is your account address.
    to : The wallet address to receive coin or SCORE address to receive a transaction
    step_limit : The maximum step value for processing a transaction
    nid : Network ID. Default nid is 1 if you didn't set the value. (1 for Main net, etc)
    nonce : An arbitrary number used to prevent transaction hash collision
    content_type : Content's MIME type
    content : Binary data of the SCORE
    params : Parameters passed on the SCORE methods ; on_install (), on_update (). Data type of the params should be dict. (optional)
    version : Protocol version (3 for V3). The default version is 3 if you didn't set the value.
    timestamp : Transaction creation time. Timestamp is in microseconds. Default timestamp is set, if you didn't set the value.
    build : Returns a deploy transaction object
Returns
A deploy transaction object
Example
1
# Generates an instance of transaction for deploying SCORE.
2
transaction = DeployTransactionBuilder()\
3
.from_(wallet.get_address())\
4
.to("cx00...02")\
5
.step_limit(1000000)\
6
.nid(3)\
7
.nonce(100)\
8
.content_type("application/zip")\
9
.content(b'D8\xe9...\xfc')\
10
.params(params)\
11
.build()

CallTransactionBuilder

Builder for CallTransaction object
Methods
    from_ : The wallet address making a transaction. The default address is your account address.
    to : The wallet address to receive coin or SCORE address to receive a transaction
    step_limit : The maximum step value for processing a transaction
    nid : Network ID. Default nid is 1 if you didn't set the value. (1 for Main net, etc)
    nonce : An arbitrary number used to prevent transaction hash collision
    method : Methods in the SCORE
    params : Parameters passed on the SCORE methods. Data type of the params should be dict. (optional)
    version : Protocol version (3 for V3). The default version is 3 if you didn't set the value.
    timestamp : Transaction creation time. Timestamp is in microseconds. Default timestamp is set, if you didn't set the value.
    Build : Returns a call transaction object
Returns
A call transaction object
Example
1
# Generates an instance of transaction for calling method in SCORE.
2
transaction = CallTransactionBuilder()\
3
.from_(wallet.get_address())\
4
.to("cx00...02")\
5
.step_limit(1000000)\
6
.nid(3)\
7
.nonce(100)\
8
.method("transfer")\
9
.params(params)\
10
.build()

MessageTransactionBuilder

Builder for MessageTransaction object
Methods
    from_ : The wallet address making a transaction. The default address is your account address.
    to : The wallet address to receive coin or SCORE address to receive a transaction
    stepLimit : The maximum step value for processing a transaction
    nid : Network ID. Default nid is 1 if you didn't set the value. (1 for Main net, etc)
    nonce : An arbitrary number used to prevent transaction hash collision
    data : Data by the dataType. Data type of the data should be string.
    version : Protocol version (3 for V3). The default version is 3 if you didn't set the value.
    timestamp : Transaction creation time. Timestamp is in microseconds. Default timestamp is set, if you didn't set the value.
    build : Returns a message transaction object
Returns
A message transaction object
Example
1
# Generates an instance of transaction for sending a message.
2
transaction = MessageTransactionBuilder()\
3
.from_(wallet.get_address())\
4
.to("cx00...02")\
5
.step_limit(1000000)\
6
.nid(3)\
7
.nonce(100)\
8
.data("test")\
9
.build()

SignedTransaction

1
SignedTransaction(transaction: Transaction, wallet: Wallet)
Returns the signed transaction object having a signature
Parameters
    transaction : A transaction object not having a signature field yet
    wallet : A wallet object
Returns
The signed transaction object having a signature field finally
Error Cases
    DataTypeException : Data type is invalid.
Example
1
# Returns the signed transaction object having a signature
2
signed_transaction = SignedTransaction(transaction, wallet)

send_transaction

1
send_transaction(signed_transaction: SignedTransaction)
Sends the transaction
Delegates to icx_sendTransaction RPC method
Need to wait for a while after sending the transaction. Because it takes time to make a consensus among nodes. We recommend 0.3 second at least.
Parameters
signed_transaction : A signed transaction object
Returns
Transaction hash prefixed with '0x'
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Sends the transaction
2
tx_hash = icon_service.send_transaction(signed_transaction)

Estimating Step

It is important to set a proper step_limit value in your transaction to make the submitted transaction executed successfully.
estimate_step API provides a way to estimate the Step usage of a given transaction. Using the method, you can get an estimated Step usage before sending your transaction, then based on the estimation, decide the optimal step_limit in your SignedTransaction.
Note: You’ll need to have iconsdk 1.0.9 or later on your local development machine to use 'estimate_step' API.

Examples

1
# Generates a raw transaction without the stepLimit
2
transaction = TransactionBuilder()\
3
.from_(wallet.get_address())\
4
.to("cx00...02")\
5
.value(150000000)\
6
.nid(3)\
7
.nonce(100)\
8
.build()
9
​
10
# Returns an estimated step value
11
estimate_step = icon_service.estimate_step(transaction)
12
# Adds some margin to the estimated step
13
step_limit = estimate_step + 10000
14
# Returns the signed transaction object having a signature with the same raw transaction and the estimated step
15
signed_transaction = SignedTransaction(transaction, wallet, step_limit)
16
# Sends the transaction
17
tx_hash = icon_service.send_transaction(signed_transaction)
Note that the estimation can be smaller or larger than the actual amount of step to be used by the transaction, so it is recommended to add some margin to the estimation when you set the step_limit of the SignedTransaction.

estimate_step

1
estimate_step(transaction: Transaction)
Returns an estimated step of how much step is necessary to allow the transaction to complete
Delegates to debug_estimateStep RPC method
Parameters
transaction : An Transaction object made by TransactionBuilder
Returns
Number of an estimated step
Error Cases
    DataTypeException : Data type is invalid.
    JSONRPCException : JSON-RPC Response is error.
Example
1
# Generates a raw transaction without the stepLimit
2
transaction = TransactionBuilder()\
3
.from_(wallet.get_address())\
4
.to("cx00...02")\
5
.value(150000000)\
6
.nid(3)\
7
.nonce(100)\
8
.build()
9
​
10
# Returns an estimated step value
11
estimate_step = icon_service.estimate_step(transaction)

Reference