## API description
This API is designed for provide following interaction:
![[Pasted image 20240607143256.png]]
`Request` is just a usual GET request on `localhost:8045`
Contents:
- [[5. WEB3 API#Request types|Request types]]
- [[5. WEB3 API#JSON application|JSON application]]
- [[5. WEB3 API#JSON file|JSON file]]
- [[5. WEB3 API#JSON file example with several items|JSON file example with several items]]
## Request types
`Request structure:`
```
Request Name
function (parameters)
request description
```
### 1. Connect
- `Connect ()`
connect to [[Wallet Overview|Cellframe Wallet]]
After successful connection you will receive a unique ID, which will be used in any request.
> [!ERROR] Important
> ID is given during the GUI or Wallet session. Upon restarting one of these, you have to execute "Connect()" again for work with WEB API.
### 2. GetNetworks
- `GetNetworks (id)`
get network list
### 3. GetWallets
- `GetWallets (id)`
get wallets list
Request example on VUE:
```js
async GetWallets() {
try {
const response = await axios.get(this.engineUrl,
{
params:
{
method: 'GetWallets',
id: this.id
}
})
this.getWalletsData = response.data
} catch(error)
{
console.log(error)
}
}
```
### 4. GetDataWallet
- `GetDataWallet (id,walletName)`
get data (balance, networks, addresses, token tickers) from the specified wallet
```actionscript
walletName - name of the wallet
```
### 5. SendTransaction
- `SendTransaction (id, net, walletName, toAddr, tokenName, value)`
execute transaction
```actionscript
net - name of the network
walletName - name of the wallet
toAddr - address of the wallet for coin transfer
tokenName - name of the token
value - quantity of coins in datoshi (token *10^18)
```
### 6. GetTransactions
- `GetTransactions (id, addr, net)`
get transaction history for every wallet in the specified network
```actionscript
addr - address of the wallet
net - name of the network
```
### 7. TxCreateJson
- `TxCreateJson (id, json)`
create custom transaction from JSON.file with arbitrary parameters
JSON file is created corresponding to JSON structure in the [[5. WEB3 API#JSON application|Application]]
### 8. GetLedgerTxHash
- `GetLedgerTxHash (id, hashTx, net)`
get information about specified transaction in the [[ledger]]
```actionscript
hashTx- hash of the transaction
net - name of the network
```
### 9. GetCertificates
- `GetCertificates(id, categoryCert)`
get certificates list
```actionscript
categoryCert - private\public\all
```
### 10. CreateCertificate
- `CreateCertificate(id, certType, certName, categoryCert)`
create certificate with specified name and type
```actionscript
certType - sig_dil\sig_bliss\sig_picnic (sig_dil is by default)
categoryCert - private\public
```
### 11. StakeLockTake
- `StakeLockTake(id, walletName, net, hashTx) `
get stacked coins
```actionscript
walletName - name of the wallet
net - name of the network
hashTx - hash of the transaction
```
### 12. StakeLockHold
- `StakeLockHold(id, tokenName, walletName, timeStaking,net, value, reinvest, stakeNoBaseFlag)`
create staking transaction
```actionscript
tokenName - name of the token
timeStaking - time until unstaking (YYMMDD)
value - coins value for staking
reinvest - percent of reward reinvesting
stakeNoBaseFlag - without base transaction - "1", with base transaction - ""
```
### 13. GetMempoolList
- `GetMempoolList (net)`
get [[Mempool]] list on the specified network
```actionscript
net - name of the network
addr - datums in the mempool which are connected to specified wallet (optional)
chain - name of the chain - main\zerochain (optional)
```
### 14. GetMempoolTxHash
- `GetMempoolTxHash(net, hashTx`
get information about transaction presence in the mempool of the specified network
```actionscript
hashTx - hash of the transaction
net - name of the network
```
### 15. CondTxCreate
- `CondTxCreate(id,net, tokenName, walletName, certName, value, unit, srv_uid)`
create custom transaction for node services payment
```actionscript
net - name of the network
tokenName - name of the token
walletName - name of the wallet which is used for payment
certName - name of the public certificate
value - quantity of coins for payment
unit - type of service unit - mb\kb\b\sec\day (mb is by default)
srv_uid - UID of the service (1 is for VPN service)
```
Request example:
```actionscript
http://127.0.0.1:8045/?method=CondTxCreate
&id=0x95480E0CDD1B6F64EEB858876E25352B10BE32258C38AC77BC8F06FBAA3E1EF1
&net=kelvpn-minkowski
&tokenName=tKEL
&walletName=mywallet
&certName=myCert_public
&value=1
&unit=day
&srv_uid=1
```
### 16. GetOrdersList
- `GetOrdersList(id, net, direction, srv_uid, unit, tokenName, price_min, price_max)`
get orders full list or using filtration by parameters
```actionscript
net - name of the network
direction - type of exchange - sell\buy (optional)
price_min - minimum value of order in datoshi (optional)
price_max - maximum value of order in datoshi (optional)
tokenName - name of the token (optional)
unit - type of the service unit (optional):
SERV_UNIT_UNDEFINED = 0 ,
SERV_UNIT_MB = 1, // megabytes
SERV_UNIT_SEC = 2, // seconds
SERV_UNIT_DAY = 3, // days
SERV_UNIT_KB = 10, // kilobytes
SERV_UNIT_B = 11, // bytes
SERV_UNIT_PCS = 22 // pieces
srv_uid - UID of the service (1 is for VPN service) (optional)
```
### 17. CreateOrder
- `CreateOrder(id, net, direction, srv_uid, value, unit, tokenName, certName, addr, hashTx, expires, ext, region, continent)`
create order for node services payment
```actionscript
net - name of the network
direction - type of exchange (sell \ buy)
value - cost of order in datoshi
certName - name of the certificate
tokenName - name of the token
addr - address of the node (optional)
hashTx - hash of the conditional transaction applied to order (optional)
expires - Unix time which shows when order expires (in seconds) (optional)
ext - extended custom parameters (string) (optional)
region - region (country) (optional)
continent - name of the continent where node is located (None, Africa, Europe, North America, South America, Southeast Asia, Asia, Oceania, Antarctica) (optional)
unit - unit type ("MB", "SEC", "DAY", "KB", "B", "PCS", MB is by default)
srv_uid - UID of the service (1 is for VPN service)
```
### 18. GetDexOrderList
- `GetDexOrderList(id)`
get list of DEX orders in all available networks
### 19. GetDexPairs
- `GetDexPairs(id)`
get list of DEX token pairs in all available networks
### 20. GetDexPairRate
- `GetDexPairRate(id, net, tokenFrom, tokenTo)`
get token rate (token buy/token sell)
```actionscript
net - name of the network
tokenFrom - token sell
tokenTo - token buy
```
### 21. DexOrderPurchase
- `DexOrderPurchase(id, hashTx, net, walletName, value)`
exchange token corresponding to specified order
```actionscript
hashTx - hash of the target order
net - name of the network
walletName - name of the wallet
value - amount of tokens are being exchanged
```
### 22. GetNodeStatus
- `GetNodeStatus(id)`
get actual node status using connection to notify socket
### 23. GetVersions
- `GetVersions(id)`
get version of wallet and node
### 24. NodeAdd
- `NodeAdd(id, net)`
add a node in the node list of the network
```actionscript
net - name of the network where node is registered
```
### 25. GetNodeIP
- `GetNodeIP(id, net, {addr | jsonArray})`
get IP address of the node using its address in the network
```actionscript
net - name of the network where node is registered
addr - address of the node in the network
jsonArray - addresses array represented as JsonArray structure
```
### 26. NodeDump
- `NodeDump(id, net)`
get node description
```actionscript
net - name of the network
```
### 27. GetNodeNetState
- `GetNodeNetState(id, net)`
get network information about node
```actionscript
net - name of the network
```
### 28. GetFee
- `GetFee(id, net)`
get information about fees in the network (network fee, validator's fee, service fee)
```actionscript
net - name of the network
```
### 29. GetListKeys
- `GetListKeys(id, net)`
get list of delegated keys in the network
```actionscript
net - name of the network
```
### 30. GetNetId
- `GetNetId(id, net)`
get network ID
```actionscript
net - name of the network
```
### 31. VotingCreate
- `VotingCreate (net, walletName, question, voteOptions)`
create poll in the Cellframe network using voting transaction
```
net - name of the network
walletName - name of the wallet, from which fee will be paid
question - subject of voting (string in quotes)
voteOptions - answer options (strings in quotes, divided by commas)
expire - timestamp of poll expiration (optional, time format - RCF822)
maxVotesCount - maximum votes quantity counter (optional)
delegatedKeyRequired - allows to vote only users who have a delegated key (optional)
voteChangingAllowed - allows to change previously sent answer (optional)
```
Request example:
```actionscript
http://127.0.0.1:8045/method=VotingCreate
&id=0x15EDD69D7A11E1E265C72629947F5ED4CF24AC1E3A14BCC8DAF7F48E7C62B6A8
&net=riemann
&walletName=W1
&question="question?"
&voteOptions="answer1","answer2","answer3"
```
### 32. VotingVote
- `VotingVote(net, walletName, hashTx,optionIdx)`
vote for chosen answer
```
net - name of the network
walletName - name of the wallet, from which fee will be paid
hashTx - hash of the voting transaction
optionIdx - index of answer option (counts from 0)
certName - name of the certificate for signing poll's result (optional)
```
Request example:
```actionscript
http://127.0.0.1:8045/method=VotingVote
&id=0xEDE916186BE739765402192B27E73159461AF33CC0788896D160CB9F349F1F77
&net=riemann
&walletName=W1
&hashTx=0x70920848EA94F08D60376775AEED233B64665B42DE1937FEA926513C1990E79D
&optionIdx=2
```
### 33. VotingList
- `VotingList (net)`
get list of actual polls in the network
```actionscript
net - name of the network
```
Request example:
```actionscript
http://127.0.0.1:8045/?method=VotingList
&id=0xEDE916186BE739765402192B27E73159461AF33CC0788896D160CB9F349F1F77
&net=riemann
```
### 34. VotingDump
- `VotingDump (net, hashTx)`
get dump about specified poll
```
net - name of the network
hashTx - hash of the voting transaction
```
Request example:
```actionscript
http://127.0.0.1:8045/?method=VotingDump
&id=0x31609198E0909B2F4E93AF48DACE87E8E088C905F92F20D204AFB92CEC1F2441
&net=riemann
&hashTx=0x70920848EA94F08D60376775AEED233B64665B42DE1937FEA926513C1990E79D
```
### 35. NodeList
- `NodeList(id, net)`
get node list of the network
```actionscript
net - name of the network
```
RemoveItemQueue(id, idQueue, net, walletName, addParam, type) - Удаляет одну или несколько транзакций из очереди.
### 36. RemoveItemQueue
- `RemoveItemQueue(id, net, idQueue, type, walletName, addParam)`
delete one or several transactions from the queue
```actionscript
net - name of the network
idQueue - ID of the transaction which is generated by queue for internal usage, this parameter is necessary for single transaction deletion, but it can not be deleted if it has null position in queue (for proper usage specify parameter type=single)
type - (=single/all) if "all" is chosen, then all transactions will be deleted except one which has null position in the queue
walletName - the name of the wallet
addParam - (=hard) this parameter allows to delete even null transaction (optional)
```
### 37. GetQueueHash
- `GetQueueHash(id, net, idQueue, walletName)`
get info about transaction in the queue
```actionscript
net - name of the network
idQueue - ID of the transaction which is generated by queue for internal usage
walletName - the name of the wallet
```
### 38. CreateOrderStaker
- `CreateOrderStaker(net, walletName, value, tax)`
create an [[Node Command - SRV_STAKE ORDER CREATE STAKER|order that allows the staker]] to transfer a certain amount of [[Token Delegated (m-token)|m-tokens]] to the owner of the master node. In return, the owner of the master node delegates his private key to the staker and must also send him a percentage of future profits
```actionscript
net - name of the network
walletName - the name of the wallet
value - amount of m-tokens
tax - percent of profite (for example, 20.0 is 20%)
```
### 39. CreateOrderValidator
- `CreateOrderValidator(net, valueMin, valueMax, tax, certName)`
create a [[Node Command - SRV_STAKE ORDER CREATE VALIDATOR|validator order]] that allows a machine owner who does not have [[Token Delegated (m-token)|m-tokens]] to establish a master node
```actionscript
net - name of the network
valueMin - minimal stake value
valueMax - maximal stake value
tax - percent of profite (for example, 20.0 is 20%)
certName - the name of the private certificate which is used for sign blocks
```
## JSON application
Description of a command which creates transaction using JSON-file.
`Command syntax:`
```actionscript
tx_create_json
[-net <net name>]
[-chain <chain name>]
-json <json file path>
```
`Options:`
```actionscript
-net - name of the Cellframe Network. The list of networks can be found in the <Config_dir> \ etc \ network folder or received by The Cellframe-Node-CLI using command - net list
-chain - the name of Chain. The list of chains can be found in the directory <Config_dir> \ etc \ network \ <network_name> or by the Cellframe-Node-CLI using command - net list chains
-json - path to json file (file.json can be situated in any folder you want)
```
> [!HINT] Note
> If the network isn't specified, it must be in a json file.
If the chain isn't specified, then the transaction will be created in the "main" chain by default.
JSON file contains all information about transactions being created.
Example:
`Command:`
```actionscript
cellframe-node-cli tx_create_json
-net foobar
-chain main
-json /root/tx.json
```
`Response:`
```actionscript
Transaction 0x1CF55991C6B14B30484BCE6B2E0CBFBD4A22D6000AD725213F3E5135E1FDBB95 with 4 items created and added to mempool successfully
```
## JSON file
Format example:
```json
{
"chain": "main",
"items": [
{
"addr_from": "Rj7J7MiX2bWy8sNybTStGPaBEJLjxMnyXJinDezXE8D5LGUmkQZSPfXHATXePY9PXi5qWo4NLRUWu89AjQ5QmEWCH1C9H7zYqceKHrTF",
"token": "CELL",
"type": "in"
},
{
"addr": "Rj7J7MiX2bWy8sNya4sPJaQsAqhULtVZi51JFSpXKKx7B5JDjbGtXPjN943iLFJuaHe3PukbBWzUM5VSo6HQZ6DkLUvnKUQVQVjLAnum",
"type": "out",
"value": "1000000000000000000"
},
{
"type": "sign",
"wallet": "testwallet"
},
{
"subtype": "fee",
"type": "out_cond",
"value": "500000000000000000"
}
],
"net": "Backbone"
}
```
### Description
Parameters `net` and `chain` define the network and the chain where transactions will be put (`net` and `chain` have priority in the command line).
Parameter `items` is an array and it contains a list of transaction's items.
```actionscript
type [string] defines the type of the item
values: in, out, out_ext, sign, in_cond, out_cond, receipt
```
There can be many items of one type.
Every item has its own additional parameters.
TYPE IN:
```actionscript
INPUT
token[string] - name of the token
addr_from[string] - address of the sender (is not required if there prev_hash and out_prev_idx are specified)
or
prev_hash [string] - hash of the previous transaction
and
out_prev_idx [int] - sequence number of output in the previous transaction
If an address was specified, then hash and number are found automatically, and output item with unspent sum is created
```
TYPE OUT:
```
OUTPUT
value[string] - number of datoshi for transfer
addr[string] - address of the receiver
```
TYPE OUT_EXT:
```
OUTPUT EXTENDED
value[string] - number of datoshi for transfer
addr[string] - address of the receiver
token[string] - name of the token
```
TYPE SIGN:
```
SIGNATURE
wallet - wallet for transaction signing
cert - certificate for transaction signing
Must be specified one of the parameters, if there both wallet and certificate names are specified, then the wallet will be used
```
TYPE RECEIPT:
```
RECEIPT
value[string] - value in datoshi
unit[int] - quantity of spent units
price_unit[string] - units type (mb or sec)
service_id[int] - ID of the service
service[string] - name of the service (fee, srv_vpn, srv_xchange, srv_stake)
params[string] - additional parameters (optional)
```
TYPE IN_COND:
```actionscript
CONDITIONAL INPUT
token[string] - name of the token
receipt_idx [int] - sequence number of receipt in the transaction (is not specified if there is only one receipt in the transaction)
addr_from[string] - sender address (is not required if there prev_hash, out_prev_idx and receipt_idx are specified)
subtype [string] - subtype of the conditional output (fee, srv_pay, srv_xchange, srv_vpn)
prev_hash [string] - hash of the previous transaction (is not required if there address and subtype are specified)
out_prev_idx [int] - sequence number of the output in the previous transaction (is not required if there address and subtype are specified)
If address and subtype were specified, then hash and number are found automatically, and output item with unspent sum is created
```
TYPE OUT_COND:
```actionscript
CONDITIONAL OUTPUT
subtype [string] - defines subtype of conditional out
values: fee, srv_pay, srv_xchange, srv_stake
```
SUBTYPE FEE:
```
FEE FOR TRANSACTION PROVIDING
value[string] - fee value in datoshi
```
SUBTYPE SRV_PAY:
```
PAY
currently, is used only for VPN service payment
value[string] - payment value in datoshi
value_max_per_unit[string] - maximum price per one unit in datoshi
price_unit[string] - type of the unit (mb or sec)
service_id[int] - ID of the service used (if not specified, then the name of the service is being found)
service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)
If the service was not specified, then srv_vpn is used by default
params[string] - additional parameters (optional)
```
SUBTYPE SRV_XCHANGE:
```
XCHANGE
currently, is used in the DEX
value[string] - payment value in datoshi
token[string] - name of the token
net[string] - name of the network
service_id[int] - ID of the service used (if not specified, then the name of the service is being found)
service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)
If the service was not specified, then srv_xchange is used by default
params[string] - additional parameters (optional)
```
SUBTYPE SRV_STAKE_POS_DELEGATE:
```
DELEGATED STAKE
currently is used in the staking service
value[string] - payment value in datoshi
fee[string] - staker's fee
fee_addr[string] - address of the fee receiver
hldr_addr[string] - address of the node holder
signing_addr[string] - address of the one, who signs transaction
service_id[int] - ID of the service used (if not specified, then the name of the service is being found)
service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)
If the service was not specified, then srv_stake is used by default
params[string] - additional parameters (optional)
```
SUBTYPE SRV_STAKE_LOCK:
```
STAKING LOCK
currently is used in the staking service
value[string] - payment value in datoshi
time_unlock[int] - time for the tokens to be locked on the wallet
reinvest percent[int] - percent of reinvesting funds from the staking profit
service_id[int] - ID of the service used (if not specified, then the name of the service is being found)
service[string] - name of the service used (srv_vpn, srv_xchange, srv_stake_pos, srv_take_lock)
params[string] - additional parameters (optional)
```
### JSON file example with several items
```json
{
"net" : "kelvin-testnet",
"chain" : "zerochain",
"items" : [ {
"type" : "in",
"prev_hash" : "0xB5A01C52D6AFAFD4860172F4057A9BDF5E7AAB5A5AD9BE574EA919DB27EFBC0B",
"out_prev_idx" : 2,
"token" : "COIN"
}, {
"type" : "in",
"addr_from" : "RpiDC8c1SxrTF3aSu2VL4Pwu8beWMY8ur71TeiR6ViBdnvMQCKudoWkvT8BGFN2ycKnHSaGm5WrNccex2qiZjA4PoEicUmWJNvRQQJYN",
"token" : "COIN"
}, {
"type" : "out",
"value" : "12345",
"addr" : "RpiDC8c1SxrTF3aSu2VL4Pwu8beWMY8ur71TeiR6ViBdnvMQCKudoWkvT8BGFN2ycKnHSaGm5WrNccex2qiZjA4PoEicUmWJNvRQQJYN",
"token" : "COIN"
}, {
"type" : "out_ext",
"value" : "100000000000",
"addr_from" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"token" : "COIN"
}, {
"type" : "receipt",
"value" : "1000",
"units" : 50,
"price_unit" : "sec",
"service" : "srv_stake",
"params" : "add parameters"
}, {
"type" : "in_cond",
"prev_hash" : "0xE48B9C5BA30AD8E79525C3E1101EC5D6BE0837E1E44E1C8BA6D3C7B9CD077890",
"out_prev_idx" : 2,
"receipt_idx" : 0
}, {
"type" : "in_cond",
"subtype" : "srv_pay",
"addr_from" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"token" : "COIN"
}, {
"type" : "out_cond",
"subtype" : "fee",
"value" : "100000000000"
}, {
"type" : "out_cond",
"subtype" : "srv_pay",
"value" : "1000",
"value_max_per_unit" : "100000",
"price_unit" : "sec",
"service_id" : 1,
"service" : "srv_vpn",
"params" : "add parameters"
}, {
"type" : "out_cond",
"subtype" : "srv_xchange",
"net" : "kelvin-testnet",
"service" : "srv_xchange",
"token" : "COIN",
"value" : "10000",
"params" : "add parameters"
}, {
"type" : "out_cond",
"subtype" : "srv_stake",
"service" : "srv_xchange",
"value" : "1230000000",
"fee" : "1000",
"fee_addr" : "RpiDC8c1SxrTF3aStZGbD94opb1SaJHAfkvcASyHz9DTrDs739WfvjJDLLGsvHJr8jb7tyiFkasuMFCgx1kjbXEFLV3G7YFQGV5ubaJK",
"hldr_addr" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"signing_addr" : "RpiDC8c1SxrTF3aSteGk3THSTbS7MYfNLsYKqUsKn9NpeHQ4mVuTB4w4NHKp4qGFH71vXXSFTbJgjDGvyyS3zAtMwjyy33WVtALJW52Z",
"node_addr" : "F2F1::AC00::0000::0001",
"params" : "add parameters"
}, {
"type" : "sign",
"wallet" : "myk",
}, {
"type" : "sign",
"cert" : "mypvt"
} ]
}
```