Search…
Economics Extension
Economic policies on the ICON network are sometimes referred to as ICON Incentives Scoring System (IISS).

Introduction

This document explains JSON-RPC APIs (version 3) for IISS available to interact with Goloop nodes.
This document was written based on IISS 3.1

IISS APIs

API path : <scheme>://<host>/api/v3
  • All IISS APIs follow SCORE API call convention
  • Target SCORE Address for IISS APIs: cx0000000000000000000000000000000000000000
  • Each IISS API TX method section explains the content of data field in icx_sendTransaction
  • Each IISS API QUERY method section explains the content of data field in icx_call
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"version": "0x3",
"from": "hx8f21e5c54f016b6a5d5fe65486908592151a7c57",
"to": "cx0000000000000000000000000000000000000000",
"stepLimit": "0x7e3a85",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x0",
"value": "0x0",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m5...",
"dataType": "call",
"data": {
"method": "setStake",
"params": {
"value": "0x1"
}
}
}
}

setStake

Stake some amount of ICX
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setStake",
"params": {
"value": "0xde0b6b3a7640000"
}
},
...
}
}

Parameters

Key
VALUE Type
Required
Description
value
T_INT
true
Amount of ICX icons in loop to stake

getStake

Returns the stake status of a given address
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "getStake",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
}
}
}

Parameters

Key
VALUE Type
Required
Description
address
T_ADDR_EOA
true
Address to query
Example responses
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"stake": "0x4e1003b28d9280000",
"unstakes": [
{
"unstake": "0x8ac7230489e80000",
"unstakeBlockHeight": "0x19",
"remainingBlocks": "0x11"
}
]
}
}

Returns

Key
VALUE Type
Required
Description
stake
T_INT
true
ICX amount of stake in loop
unstakes
T_LIST[T_DICT]
false
Unstake info list
unstakes.unstake
T_INT
false
ICX amount of unstake in loop
unstakes.unstakeBlockHeight
T_INT
false
BlockHeight when unstake will be done

setDelegation

Delegate some ICX amount of stake to P-Reps
  • Maximum number of P-Reps to delegate is 100
  • The transaction which has duplicated P-Rep addresses will be failed
  • This transaction overwrites the previous delegate information
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setDelegation",
"params": {
"delegations": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3200000000"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x1000000000"
}
]
}
},
...
}
}
Request to revoke all delegations
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setDelegation",
"params": {
"delegations": []
}
},
...
}
}

Parameters

Key
VALUE Type
Required
Description
delegations
T_LIST(T_DICT)
true
List of delegation dict (MAX: 100 entries)
delegations.address
T_ADDR_EOA
true
Address of P-Rep to delegate
delegations.value
T_INT
true
Delegation amount in loop

getDelegation

Returns the delegation status of a given address
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "getDelegation",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
}
}
}

Parameters

Key
VALUE Type
Required
Description
address
T_ADDR_EOA
true
Address to query
Example responses
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"totalDelegated": "0xa688906bd8b0000",
"votingPower": "0x3782dace9d90000",
"delegations": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3782dace9d90000"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x6f05b59d3b20000"
}
]
}
}

Returns

Key
VALUE Type
Required
Description
totalDelegated
T_INT
true
The sum of delegation amount
votingPower
T_INT
true
Remaining amount of stake that ICONist can delegate to other P-Reps
delegations
T_LIST(T_DICT)
true
List of delegation dict (MAX: 100 entries)
delegations.address
T_ADDR_EOA
true
Address of P-Rep to delegate
delegations.value
T_INT
true
Delegation amount in loop

setBond

Bond some ICX amount of stake to P-Reps
  • Maximum number of P-Reps to bond is 100
  • The transaction which has duplicated P-Rep addresses will be failed
  • This transaction overwrites the previous bond information
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setBond",
"params": {
"bonds": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3200000000"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x1000000000"
}
]
}
},
...
}
}

Parameters

Key
VALUE Type
Required
Description
bonds
T_LIST(T_DICT)
true
List of bond dict (MAX: 100 entries)
bonds.address
T_ADDR_EOA
true
Address of P-Rep to bond
bonds.value
T_INT
true
Bond amount in loop

getBond

Returns the bond status of a given address
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "getBond",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
}
}
}

Parameters

Key
VALUE Type
Required
Description
address
T_ADDR_EOA
true
Address to query
Example responses
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"bonds": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3782dace9d90000"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x6f05b59d3b20000"
}
],
"unbonds": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3782dace9d90000",
"expireBlockHeight": "0xa"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x6f05b59d3b20000",
"expireBlockHeight": "0xa"
}
]
}
}

Returns

Key
VALUE Type
Required
Description
bonds
T_LIST(T_DICT)
true
List of bond dict
bonds.address
T_ADDR_EOA,T_ADDR_SCORE
true
Address of P-Rep to delegate
bonds.value
T_INT
true
Bond amount in loop
unbonds
T_LIST(T_DICT)
true
List of unbond dict
unbonds.address
T_ADDR_EOA,T_ADDR_SCORE
true
Address of P-Rep to delegate
unbonds.value
T_INT
true
Unbonding amount in loop
unbonds.expireBlockHeight
T_INT
true
BlockHeight when unBonding will be done

claimIScore

Claim the total reward that a ICONist has received
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "claimIScore"
},
...
}
}

Parameters

N/A

EventLog

Name
Data Type
Indexed
Description
IScoreClaimedV2(Address,int,int)
T_STRING
true
Signature
IScore
T_INT
false
Reward amount in IScore
ICX
T_INT
false
Reward amount in loop

queryIScore

Returns the amount of I-Score that a ICONist has received as a reward
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "queryIScore",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
}
}
}

Parameters

Key
VALUE Type
Required
Description
address
T_ADDR_EOA
true
Address to query
Example responses
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"blockHeight": "0xe3d2",
"iscore": "0x3e8",
"estimatedICX": "0x1"
}
}

Returns

Key
VALUE Type
Required
Description
blockHeight
T_INT
true
Block height when I-Score is estimated
iscore
T_INT
true
Amount of I-Score
estimatedICX
T_INT
true
Estimated amount in loop 1000 I-Score == 1 loop

registerPRep

Register an address as a P-Rep to Blockchain
  • 2000 ICX are required as a registration fee
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"value": "0x6c6b935b8bbd400000",
"data": {
"method": "registerPRep",
"params": {
"name": "ABC Node",
"country": "KOR",
"city": "Seoul",
"email": "[email protected]",
"website": "https://abc.example.com/",
"details": "https://abc.example.com/details/",
"p2pEndpoint": "abc.example.com:7100",
"nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
},
...
}
}

Parameters

Key
VALUE Type
Required
Description
name
T_STRING
true
P-Rep name "ABC Node"
email
T_STRING
true
P-Rep email "[email protected]"
country
T_STRING
true
ISO 3166-1 ALPHA-3 "KOR", "USA", "CHN"
city
T_STRING
true
"Seoul", "New York", "Paris"
website
T_STRING
true
P-Rep homepage url "https://abc.example.com"
detailes
T_STRING
true
Url including P-Rep detail information "https://abc.example.com/details/"
p2pEndpoint
T_STRING
true
Network info used for connecting among P-Rep nodes "123.45.67.89:7100", "node.example.com:7100"
nodeAddress
T_STRING
False
Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"

EventLog

Name
Data Type
Indexed
Description
PRepRegistered(Address)
T_STRING
true
Signature
Address
T_ADDR_EOA
false
P-Rep address

unregisterPRep

Unregister a P-Rep
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "unregisterPRep"
},
...
}
}

Parameters

N/A

EventLog

Name
Data Type
Indexed
Description
PRepUnregistered(Address)
T_STRING
true
Signature
Address
T_ADDR_EOA
false
P-Rep address

setPRep

Update P-Rep register information
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setPRep",
"params": {
"name": "Banana Node",
"email": "[email protected]",
"nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
},
...
}
}

Parameters

Key
VALUE Type
Required
Description
name
T_STRING
false
P-Rep name "ABC Node"
email
T_STRING
false
P-Rep email "[email protected]"
country
T_STRING
false
ISO 3166-1 ALPHA-3 "KOR", "USA", "CHN"
city
T_STRING
false
"Seoul", "New York", "Paris"
website
T_STRING
false
P-Rep homepage url "https://abc.example.com"
detailes
T_STRING
false
Url including P-Rep detail information "https://abc.example.com/details/"
p2pEndpoint
T_STRING
false
Network info used for connecting among P-Rep nodes "123.45.67.89:7100", "node.example.com:7100"
nodeAddress
T_STRING
false
Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"

EventLog

Name
Data Type
Indexed
Description
PRepSet(Address)
T_STRING
true
Signature
Address
T_ADDR_EOA
false
P-Rep address

getPRep

Returns P-Rep register information
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "getPRep",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
}
}
}

Parameters

Key
VALUE Type
Required
Description
address
T_ADDR_EOA
true
Address to query
Example responses
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"status": "0x0",
"grade": "0x2",
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
"name": "banana",
"country": "KOR",
"city": "Seoul",
"email": "[email protected]",
"website": "https://icon.banana.com",
"details": "https://icon.banana.com/json",
"p2pEndpoint": "123.45.67.89:7100",
"nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
"irep": "0xa968163f0a57b400000",
"irepUpdateBlockHeight": "0x847ea",
"stake": "0x38372",
"delegated": "0x74287392847",
"totalBlocks": "0x83261e7",
"validatedBlocks": "0x83258a9"
}
}

Returns

Key
VALUE Type
Required
Description
status
T_INT
true
0: active 1: unregistered
grade
T_INT
true
0: Main P-Rep 1: Sub P-Rep 2: P-Rep candidate
address
T_ADDR_EOA
true
P-Rep address
name
T_STRING
true
P-Rep name "ABC Node"
email
T_STRING
true
P-Rep email "[email protected]"
country
T_STRING
true
ISO 3166-1 ALPHA-3 "KOR", "USA", "CHN"
city
T_STRING
true
"Seoul", "New York", "Paris"
website
T_STRING
true
P-Rep homepage url "https://abc.example.com"
detailes
T_STRING
true
Url including P-Rep detail information "https://abc.example.com/details/"
p2pEndpoint
T_STRING
true
Network info used for connecting among P-Rep nodes "123.45.67.89:7100", "node.example.com:7100"
nodeAddress
T_STRING
true
Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
irep
T_INT
true
Incentive rep used to calculate the reward for P-Rep Limit: +- 20% of the previous value Unit: loop
irepUpdatedBlockHeight
T_INT
true
Block height when a P-Rep changed I-Rep value
lastGenerateBlockHeight
T_INT
true
Height of the last block which a P-Rep generated
stake
T_INT
true
Amount of stake that a P-Rep has
delegated
T_INT
true
Delegation amount that a P-Rep receives from ICONists
totalBlocks
T_INT
true
The number of blocks that a P-Rep received when running as a Main P-Rep
validatedBlocks
T_INT
true
The number of blocks that a P-Rep validated when running as a Main P-Rep

getPReps

Returns the status of all registered P-Rep candidates in descending order by delegated ICX amount
  • Unregistered or disqualified P-Reps are not included
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "getPReps",
"params": {
"startRanking": "0x1",
"endRanking": "0xa"
}
}
}
}

Parameters

Key
VALUE Type
Required
Description
startRanking
T_INT
false
Default: 1 P-Rep list which starts from start ranking
endRanking
T_INT
false
Default: the last ranking
Example responses
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"blockHeight": "0x1234",
"startRanking": "0x1",
"totalDelegated": "0x2863c1f5cdae42f9540000000",
"totalStake": "0x193e5939a08ce9dbd480000000",
"preps": [
{
"status": "0x0",
"grade": "0x2",
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
"name": "banana",
"country": "KOR",
"city": "Seoul",
"email": "[email protected]",
"website": "https://icon.banana.com",
"details": "https://icon.banana.com/json",
"p2pEndpoint": "123.45.67.89:7100",
"nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
"irep": "0xa968163f0a57b400000",
"irepUpdateBlockHeight": "0x847ea",
"stake": "0x38372",
"delegated": "0x74287392847",
"totalBlocks": "0x83261e7",
"validatedBlocks": "0x83258a9"
},
{
"status": "0x0",
"grade": "0x2",
"name": "ABC Node",
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"country": "USA",
"city": "New York",
"email": "[email protected]",
"website": "https://icon.banana.com",
"details": "https://icon.banana.com/json",
"p2pEndpoint": "123.45.67.89:7100",
"nodeAddress": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"irep": "0xc350",
"irepUpdateBlockHeight": "0x1100",
"lastGenerateBlockHeight": "0x1200",
"stake": "0x28a857425466f800000",
"delegated": "0x9ed194db19b238c000000",
"totalBlocks": "0x2720",
"validatedBlocks": "0x2348"
},
...
]
}
}

Returns

Key
VALUE Type
Required
Description
blockHeight
T_INT
true
The latest block height when this request was processed
startRanking
T_INT
true
Start ranking of P-Rep list
totalDelegated
T_INT
true
Total delegation amount that all P-Reps receive
totalStake
T_INT
true
The sum of ICX that all ICONists stake
preps
T_LIST(T_DICT)
true
P-Rep list. Details : refer to getPRep

setBonderList

Set allowed bonder list to P-Rep
  • Maximum number of allowed ICONists to bond is 10
  • This transaction overwrites the previous bonder list information
Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setBonderList",
"params": {
"bonderList": [
"hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"cxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826"
]
}
},
...
}
}

Parameters

Key
VALUE Type
Required
Description
bonderList
T_LIST(T_ADDR_EOA,T_ADDR_