Buy crypto anonymously on the Incognito pDEX   

Portal’s API documentation

#1

Welcome to Portal’s API documentation. In this document, you’ll find everything you need to start using Portal features like shield/unshield crypto coins (eg., BNB, and BTC for now). All APIs are in RPC format that can be accessed over HTTPS protocol from https://mainnet.incognito.org/fullnode domain. In addition to basic cURL requests/responses for every endpoint, you can also use any handy GUI API call tools such as Postman or others to make requests as well as receive responses with ease.

Section summaries

Become a custodian

A custodian holds public tokens deposited by users when they want to shield their assets, and are responsible for returning them to users when they want to unshield private tokens to public tokens.

Anyone can become a custodian just by supplying collateral assets and remote addresses (BTC/BNB addresses). The collaterals are in PRV.

To register to become a custodian, just simply call Custodian registration API.

To check the status of the registration, call Custodian registration status API.

Shield a public token

A user wants to shield a public token to a corresponding private token (for example, shield BNB to pBNB), follow these steps:

  • Step 1: Calculate shielding fee (0.01% of shielding amount) in PRV. See Get shielding fee API.
  • Step 2: Register shielding a public token to get a pToken with an unique shielding ID. See Register shielding API. When a user registers shielding, Portal will pick up custodians to match to the shielding request, and lock collaterals of chosen custodians. The total amount of locked collaterals is about 200% of the shielding amount in PRV (to make sure custodians don’t run away with the public tokens).
  • Step 3: Send public token to custodians on the external chain (for example, send BNB to custodians on Binance Chain) within 24 hours of the user request. Important note: the user has to attach a memo (including the unique shielding ID) to the external transaction. See Create a memo for shielding transactions in order to create a memo for the external transaction. After 24 hours, if the user hasn’t sent a public token to custodians, the shielding request will be expired.
  • Step 4: Build Merkle proof of the transaction from step 3. See Build Merkle Proof for BNB, for BTC.
  • Step 5: Submit the proof (from step 4) to Incognito chain in order to request pToken. See Request pToken API.

That is the procedure, users will receive their pToken after completing the steps above.

Unshield a private token

Users want to unshield (redeem) a private token to get a corresponding public token (for example. unshield pBNB to get BNB back), follow these steps:

  • Step 1: Calculate unshielding fee (0.01% unshielding amount) in PRV. See Get shielding fee API.

  • Step 2: Request unshielding public token from pToken with a unique unshielding ID. See Unshielding request API.

  • In order to check whether the unshielding request is a success or failure by transaction’s ID, just call Get status of an unshielding request API.

  • Portal also supplies another API, Get status of unshielding request by unshielding ID, for checking status of unshielding request by the unique unshielding ID.

  • Step 3 (Only for custodian): The custodians who have available public tokens to send back the user, can nominate themselves to match to the unshielding request within 10 minutes of the user request. See Request matching unshielding request API. After 10 minutes, if there are not enough custodians matching the unshielding request, Portal will pick up more custodians who are holding public tokens.

  • In order to check if the matching unshielding request succeeded by transaction’s ID, just call Get status of a request matching unshielding request API.

  • Step 4 (Only for custodian): The custodians who requested matching to the unshielding request, and were picked up from step 3 above, have to send a public token back to the user on the external chain within 24 hours of the user request. Similar to the shielding transaction, custodians have to attach a memo (including the unique unshielding ID and the custodian’s Incognito address) to the external transaction. See Create a memo for unshielding transactions to create a memo for the external transaction. The user will receive their own public token after this step is completed.

  • Step 5 (Only for custodian): Build Merkle proof of the transaction from step 4. See Build Merkle Proof for BNB, for BTC.

  • Step 6 (Only for custodian): Submit the proof (from step 5) to unlock collateral for the next shielding requests. See Request unlock collaterals API.

  • In order to check if the request to unlock collateral is successful by transaction’s ID, just call Get status of a request unlocking collateral API.

Auto-liquidation

Auto-liquidation is triggered in two cases:

Case 1: A custodian does not send public tokens back to users after timeout (24 hours).

  • When this case occurs, users will receive 120% of the redeem amount in PRV from the custodian’s collateral.

Case 2: A custodian’s collateral drops significantly below 120% of the value of the public tokens held by the custodian.

  • In this case, the custodian needs to add more collateral (top-up) before its value falls to critical levels.
  • Step 1: To get the collateral amount that needs to be added for a specific token, call Get Top-up Amount API.
  • Step 2: Custodians can top up their position at any time with an arbitrary amount by calling Top-up API. The best practice would be to top up with the minimum amount from step 1 to ensure that no auto-liquidation occurs.

If a custodian has been matched to a certain shielding request that hasn’t yet been completed (e.g., they are waiting for users to send public tokens to custodians) then Auto-liquidation may also kick in once the shielding process is complete if not enough collateral is present for the new request. Therefore, in order to avoid this from happening, the custodian can top up for a specific “waiting shielding” request.

If the custodian doesn’t top up then the custodian’s collateral would be liquidated automatically. Maximum amount of liquidated collateral is 120% of public token. Liquidated collateral will be moved to the liquidation pool. To get information about the liquidation pool, call Get Liquidation pool API.

Users can redeem pToken for PRV in the liquidation pool by using Redeem From Liquidation Pool API.

APIs

Custodian registration

{
     "jsonrpc": "1.0",
     "method": "createandsendtxwithcustodiandeposit",
    "params": [
         {{CustodianPrivateKey}},
      {
            "12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA": {{ColallteralAmount}}
        }, 
        -1,
        0,
        {
            "IncognitoAddress": {{CustodianIncAddr}},
            "RemoteAddresses": {
                "6abd698ea7ddd1f98b1ecaaddab5db0453b8363ff092f0d8d7d4c6b1155fb693": {{BNBAddr}},
                "ef5947f70ead81a76a53c7c8b7317dd5245510c665d3a13921dc9a581188728b": {{BTCAddr}}
            },
            "DepositedAmount": {{ColallteralAmount}}
        }
    ],
    "id": 1
}

Parameters:

  • CustodianPrivateKey (String) : custodian’s private key.
  • ColallteralAmount (String): collateral amount custodian wants to deposit.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • BNBAddr (String): Binance address.
  • BTCAddr (String): Bitcoin address.

Note: The custodian can supply only the Binance address if the custodian just wants to hold BNB. Similar to Bitcoin.

Response:

  • TxID (String): ID of the custodian deposit transaction.

Custodian registration status

{
"jsonrpc": "1.0",
"method": "getportalcustodiandepositstatus",
"params": [{
"DepositTxID" : {{TxID}}
}],
"id": 1
}

Parameters:

  • TxID (String): ID of the custodian deposit transaction.

Response:

  • Status (Number): 1 - success, 2 - failed
  • IncogAddressStr (String): custodian’s incognito payment address.
  • RemoteAddresses (Array): custodian’s remote addresses.
  • DepositedAmount (Number): the deposited collateral amount.

Register shielding

{
"jsonrpc":"1.0",
"method":"createandsendregisterportingpublictokens",
"params":[
{{UserPrivateKey}},
{
"12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA" : {{ShieldingFee}}
},
-1,
0,
{
"UniqueRegisterId": {{UniqueShieldingID}},
"IncogAddressStr" : {{UserIncAddr}},
"PTokenId": {{PTokenID}},
"RegisterAmount": {{ShieldingAmount}},
"PortingFee": {{ShieldingFee}}
}
],
"id":1
}

Parameters:

  • UserPrivateKey (String): private key of the user who wants to shield a public token.
  • UniqueShieldingID (String) : unique shielding ID.
  • UserIncAddr (String): payment address of the user who wants to shield a public token.
  • PTokenID (String): ID of pToken will be shielded.
    • pBNB ID: “6abd698ea7ddd1f98b1ecaaddab5db0453b8363ff092f0d8d7d4c6b1155fb693”
    • pBTC ID: “ef5947f70ead81a76a53c7c8b7317dd5245510c665d3a13921dc9a581188728b”
  • ShieldingAmount (String): shielding amount.
    • Ex: Shield 1 BNB to 1 pBNB, ShieldingAmount = 1e9.
  • ShieldingFee (String): shielding fee

Response:

  • TxID (String): ID of the shielding registration transaction.

Get status of shielding registration by transaction’s ID API

{
"jsonrpc": "1.0",
"method": "getportalportingrequestbykey",
"params": [{
"TxHash" : {{TxID}}
}],
"id": 1
}

Parameters:

  • TxID (String): ID of shielding registration transaction.

Response:

  • Status (Number): 1 - success, 3 - failed.

Get status of shielding registration by shielding ID API

{
"jsonrpc": "1.0",
"method": "getportalportingrequestbyportingid",
"params": [{
"PortingId" : {{UniqueShieldingID}}
}],
"id": 1
}

Parameters:

  • UniqueShieldingID (String): unique shielding ID.

Response:

  • Status (Number):
    • 1 - completed: the user submitted the proof that they user sent the public token to the custodians.
    • 2 - waiting: waiting for the user to send the public token to the custodians.
    • 3 - expired: when the user hasn’t sent the public token to the custodians after timeout.

Get shielding fee

{
"jsonrpc":"1.0",
"method":"getportingrequestfees",
"params":[{
"BeaconHeight": {{LatestBeaconHeight}},
"ValuePToken": {{TokenAmount}},
"TokenID": {{PTokenID}},
}],
"id":1
}

Parameters:

  • LatestBeaconHeight (String): the latest beacon height.
  • TokenAmount (String): porting/redeem fee.
  • PTokenID (String): pToken ID.

Response:

  • Result (Number): shielding/unshielding fee in PRV.

Request pToken

{
"jsonrpc": "1.0",
"method": "createandsendtxwithreqptoken",
"params": [
{{UserPrivateKey}},
null,
-1,
0,
{
"UniquePortingID": {{UniqueShieldingID}},
"IncogAddressStr" : {{UserIncAddr}},
"PortingAmount": {{ShieldingAmount}},
"TokenID": {{PTokenID}},
"PortingProof": {{ShieldingProof}}
}
],
"id": 1
}

Parameters:

  • UserPrivateKey (String): private key of the user who wants to request pToken.
  • UniqueShieldingID (String): unique shielding ID.
  • UserIncAddr (String): payment address of the user who wants to request pToken.
  • PTokenID (String): PToken ID.
  • ShieldingAmount (String): shielding amount.
  • ShieldingProof (String): Merkle proof of the shielding transaction.

Note: UniqueShieldingID, UserIncAddr, PTokenID, ShieldingAmount params have the same value as shielding registration parameters.

Response:

  • TxID (String): ID of the requesting ptoken transaction.

Get status of requesting ptoken by transaction’s ID API

{
"jsonrpc": "1.0",
"method": "getportalreqptokenstatus",
"params": [{
"ReqTxID" : {{TxID}}
}],
"id": 1
}

Parameters:

  • TxID (String): ID of requesting ptoken transaction.

Response:

  • Status (Number): 1 - success, 2 - failed.

Unshielding request

{
"id": 1,
"jsonrpc": "1.0",
"method": "createandsendtxwithredeemreq",
"params": [
{{UserPrivateKey}},
{
"12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA" : {{UnshieldingFee}}
},
-1,
-1,
{
"Privacy": true,
"TokenID": {{PTokenID}},
"TokenTxType": 1,
"TokenName": "",
"TokenSymbol": "",
"TokenAmount": {{UnshieldingAmount}},
"TokenReceivers": {
"12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA": {{UnshieldingAmount}}
},
"TokenFee": "0",

"UniqueRedeemID": {{UniqueUnshieldingID}},
"RedeemTokenID": {{PTokenID}},
"RedeemAmount": {{UnshieldingAmount}},
"RedeemFee": {{UnshieldingFee}},
"RedeemerIncAddressStr": {{UserIncAddr}},
"RemoteAddress": {{UserRemoteAddress}}
},
"",
0
]
}

Parameters:

  • UserPrivateKey (String): private key of the user who wants to unshield a ptoken.

  • UnshieldingFee (String): unshielding fee in PRV

  • UniqueUnshieldingID (String): unique unshielding ID.

  • PTokenID (String): ID of ptoken will be unshielded.

  • UnshieldingAmount (String): unshielding amount.

    1. Ex: Unshield 1 pBNB to 1 BNB, UnshieldingAmount = 1e9.

  • UserIncAddr (String): payment address of the user who wants to unshield a ptoken to a public token.

  • UserRemoteAddress (String): user’s remote address (BNB/BTC address).

Response:

  • TxID (String): ID of the unshielding request transaction.

Get status of unshielding request by transaction’s ID

{
"jsonrpc": "1.0",
"method": "getreqredeemstatusbytxid",
"params": [{
"ReqTxID" : {{TxID}}
}],
"id": 1
}

Parameters:

  • TxID (String): ID of unshielding request transaction.

Response:

  • Status (Number): 1 - success, 2 - failed.

Get status of unshielding request by unshielding ID

{
"jsonrpc": "1.0",
"method": "getportalreqredeemstatus",
"params": [{
"RedeemID" : {{UniqueUnshieldingID}}
}],
"id": 1
}

Parameters:

  • UniqueUnshieldingID (String): unique unshielding ID.

Response:

  • Status (Number):
    • 1 - completed: the custodian submitted proof that they sent the public token back to the user.
    • 2 - waiting: waiting for the custodians to nominate themselves for matching the unshielding request.
    • 3 - matched: there are enough custodians matching to the unshielding request, waiting for the custodians to send the public token to the user.
    • 4 - liquidated: when the custodians don’t send the public token back to the user after timeout
    • 5 - cancelled: when auto-liquidation occurs to any custodians that are matching to the unshielding request.

Request matching a unshielding request

{
"jsonrpc": "1.0",
"method": "createandsendtxwithreqmatchingredeem",
"params": [
{{CustodianPrivateKey}},
null,
-1,
0,
{
"CustodianAddressStr" : {{CustodianIncAddr}},
"RedeemID": {{UniqueUnshieldingID}}
}
],
"id": 1
}

Parameters:

  • CustodianPrivateKey (String) : custodian’s private key.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • UniqueUnshieldingID(String): unique unshielding ID that the custodian wants to match to.

Response:

  • TxID (String): ID of the request matching to unshielding request transaction.

Get status of a request matching unshielding request

{
"jsonrpc": "1.0",
"method": "getreqmatchingredeemstatus",
"params": [{
"ReqTxID" : {{TxID}}
}],
"id": 1
}

Parameters:

  • TxID (String): ID of request matching unshielding request transaction.

Response:

  • Status (Number): 1 - success, 2 - failed.

Request unlock collaterals

{
"jsonrpc": "1.0",
"method": "createandsendtxwithrequnlockcollateral",
"params": [
{{CustodianPrivateKey}},
null,
-1,
0,
{
"UniqueRedeemID": {{UniqueUnshieldingID}},
"CustodianAddressStr" : {{CustodianIncAddr}},
"TokenID": {{PTokenID}},
"RedeemAmount": {{UnshieldingAmount}},
"RedeemProof": {{UnshieldingProof}}
}
],
"id": 1
}

Parameters:

  • CustodianPrivateKey (String) : custodian’s private key.
  • UniqueUnshieldingID(String): unique unshielding ID for the custodian who wants to unlock collateral.
  • CustodianIncAddr (String): custodian’s Incognito payment address.
  • PTokenID (String): ID of ptoken in the redeem request.
  • UnshieldingAmount (String): unshielding amount that is matched to the custodian.

Response:

  • TxID (String): ID of the request unlocking collateral transaction.

Get status of request unlocking collateral

{
"jsonrpc": "1.0",
"method": "getportalrequnlockcollateralstatus",
"params": [{
"ReqTxID" : {{TxID}}
}],
"id": 1
}

Parameters:

  • TxID (String): ID of request for unlocking collateral transaction.

Response:

  • Status (Number): 1 - success, 2 - failed.

Build Merkle proof of BNB transaction

The data structure of BNB transaction proof is defined in package relaying of Incognito-chain.

type BNBProof struct {
Proof *types.TxProof
BlockHeight int64
}

Users can build BNBProof by calling the function Build(indexTx, blockHeight, url) of struct BNBProof in Incognito source code. This function needs to pass these following parameters:

  • indexTx: index of transaction in Binance block.
  • blockHeight: height of the block that contains the transaction.
  • Url: address of any Binance node to query all transactions in the block.

Another way to get TxProof is calling the API of Binance chain: Query tx by hash with “prove” param is true.

After users receive a Merkle Proof, users need to base64 encode the bytes array of BNBProof and submit it to Incognito chain.

For example:

func BuildProof(txIndex int, blockHeight int64, url string) (string, error) {
bnbProof := new(relaying.BNBProof)
err := bnbProof.Build(txIndex, blockHeight, url)
if err != nil {
return “”, err
}

bnbProofBytes, err2 := json.Marshal(bnbProof)
if err2 != nil {
return “”, err2
}

bnbProofStr := base64.StdEncoding.EncodeToString(bnbProofBytes)

return bnbProofStr, nil
}

Build Merkle proof of BTC transaction

// TBD

Create a memo for shielding transactions

For BNB transactions:

func CreateMemoForBNBShieldingTx(uniquePortingID string) string {
type PortingMemoBNB struct {
PortingID string `json:"PortingID"`
}

memoPorting := PortingMemoBNB{PortingID: uniquePortingID}
memoPortingBytes, _ := json.Marshal(memoPorting)
memoPortingStr := base64.StdEncoding.EncodeToString(memoPortingBytes)
return memoPortingStr
}

For BTC transactions:

func CreateMemoForBTCShieldingTx(uniquePortingID string) string {
hash := make([]byte, 16)
h := sha3.NewShake128()
h.Write([]byte(uniquePortingID))
h.Read(hash)
b58 := new(base58.Base58)
return b58.Encode(hash)
}

Create a memo for unshielding transactions

For BNB transactions:

func CreateMemoForBNBUnshieldingTx(uniqueRedeemID string, custodianIncAddr string) string {
type RedeemMemoBNB struct {
RedeemID string `json:"RedeemID"`
CustodianIncognitoAddress string `json:"CustodianIncognitoAddress"`
}

memoRedeem := RedeemMemoBNB{RedeemID: uniqueRedeemID, CustodianIncognitoAddress: custodianIncAddr}
memoRedeemBytes, _ := json.Marshal(memoRedeem)
memoRedeemHash := common.HashB(memoRedeemBytes)
memoRedeemStr := base64.StdEncoding.EncodeToString(memoRedeemHash)
return memoRedeemStr
}

For BTC transactions:

func CreateMemoForBTCUnshieldingTx(uniqueRedeemID string, custodianIncAddr string) string {
msg := fmt.Sprintf("%s%s", uniqueRedeemID, custodianIncAddr)
hash := make([]byte, 16)
h := sha3.NewShake128()
h.Write([]byte(msg))
h.Read(hash)
b58 := new(base58.Base58)
return b58.Encode(hash)
}

Get top-up amount

{
"jsonrpc": "1.0",
"method": "getamountneededforcustodiandepositliquidation",
"params": [{
"BeaconHeight" : {{LatestBeaconHeight}},
"TokenID": {{PTokenID}},
"CustodianAddress": {{CustodianIncAddr}}
}],
"id": 1
}

Parameters:

  • LatestBeaconHeight (String): the latest beacon height.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • PTokenID (String): ID of ptoken.

Response:

  • TokenID (String): ID of ptoken.
  • Amount (Number): Collateral amount needs to be added more.

Top-up

{
"jsonrpc": "1.0",
"method": "createandsendliquidationcustodiandeposit",
"params": [
{{CustodianPrivateKey}},
{
"12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA" : {{MoreTopupAmount}}
},
-1,
0,
{
"IncognitoAddress" : {{CustodianIncAddr}},
"DepositedAmount": {{MoreTopupAmount}},
"FreeCollateralAmount": {{TopupAmountFromFreeColateral}},
"PTokenId": {{PTokenID}}
}
],
"id": 1
}

Parameters:

  • CustodianPrivateKey (String) : custodian’s private key.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • PTokenID (String): ID of ptoken.
  • MoreTopupAmount (String): the collateral amount that the custodian adds more from the custodian’s wallet.
  • TopupAmountFromFreeCollateral (String): the collateral amount is used to top-up from free collateral of the custodian.

Response:

  • TxID (String): ID of the top-up transaction.

Get top-up amount for waiting shielding requests

{
"jsonrpc": "1.0",
"method": "getamounttopupwaitingporting",
"params": [{
"CustodianAddress": {{CustodianIncAddr}}
}],
"id": 1
}

Parameters:

  • CustodianIncAddr (String): custodian’s Incognito payment address.

Response:

  • Result (map[string]uint64): unique id of waiting shielding and corresponding top-up amount.

Top-up for a waiting shielding request

{
"jsonrpc":"1.0",
"method":"createandsendtopupwaitingporting",
"params":[
{{CustodianPrivateKey}},
{
"12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA" : {{MoreTopupAmount}}
},
-1,
0,
{
"PortingID": {{UniqueShieldingID}},
"IncognitoAddress": {{CustodianIncAddr}},
"PTokenId": {{PTokenID}},
"FreeCollateralAmount": {{TopupAmountFromFreeColateral}},
"DepositedAmount": {{MoreTopupAmount}}
}
],
"id":1
}

Parameters:

  • CustodianPrivateKey (String) : custodian’s private key.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • UniqueShieldingID (String) : ID of the unique shielding that the custodian wants to top-up.
  • PTokenID (String): ID of ptoken in this shielding request.
  • MoreTopupAmount (String): the collateral amount that the custodian adds more from the custodian’s wallet.
  • TopupAmountFromFreeCollateral (String): the collateral amount is used to top-up from free collateral of the custodian.

Response:

  • TxID (String): ID of the top-up transaction.

Get liquidation pool

{
"jsonrpc": "1.0",
"method": "getliquidationtpexchangeratespool",
"params": [{
"BeaconHeight": {{LatestBeaconHeight}},
"TokenID": {{PTokenID}}
}],
"id": 1
}

Parameters:

  • LatestBeaconHeight (String): the latest beacon height.
  • PTokenID (String): ID of ptoken.

Response:

  • CollateralAmount (Number): liquidated collateral amount.
  • PubTokenAmount (Number): liquidated public token amount.

Unshielding from liquidation pool

{
"id": 1,
"jsonrpc": "1.0",
"method": "createandsendredeemliquidationexchangerates",
"params": [
{{UserPrivateKey}},
null,
-1,
-1,
{
"Privacy": true,
"TokenID": {{PTokenID}},
"TokenTxType": 1,
"TokenName": "",
"TokenSymbol": "",
"TokenAmount": {{UnshieldingAmount}},
"TokenReceivers": {
"12RxahVABnAVCGP3LGwCn8jkQxgw7z1x14wztHzn455TTVpi1wBq9YGwkRMQg3J4e657AbAnCvYCJSdA9czBUNuCKwGSRQt55Xwz8WA": {{UnshieldingAmount}}
},
"TokenFee": 0,

"RedeemTokenID": {{PTokenID}},
"RedeemAmount": {{UnshieldingAmount}},
"RedeemerIncAddressStr": {{UserIncAddr}},
},
"",
0
]
}

Parameters

  • UserPrivateKey (String): private key of the user who wants to unshield a ptoken for PRV from the liquidation pool.

  • PTokenID (String): ID of ptoken is unshielded.

  • UnshieldingAmount (String): unshielding amount.

    1. Ex: Unshield 1 pBNB to 1 BNB, UnshieldingAmount = 1e9.

  • UserIncAddr (String): payment address of the user who wants to unshield a ptoken.

Response

  • TxID (String): ID of the unshielding request from the liquidation pool transaction.

Get portal reward of custodian

{
"jsonrpc": "1.0",
"method": "getportalreward",
"params": [{
"IncognitoAddress" : {{CustodianIncAddr}}
}],
"id": 1
}

Parameters

  • CustodianIncAddr (String): custodian’s Incognito payment address.

Response

  • Result (map[string]uint64): tokenID and corresponding reward amount.

Request withdraw portal reward

{
"jsonrpc": "1.0",
"method": "createandsendtxwithreqwithdrawrewardportal",
"params": [
{{CustodianPrivateKey}},
null,
-1,
0,
{
"CustodianAddressStr": {{CustodianIncAddr}},
"TokenID": {{PTokenID}}
}
],
"id": 1
}

Parameters

  • CustodianPrivateKey (String) : custodian’s private key.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • PTokenID (String): pToken ID.

Response

  • TxID (String): ID of the request withdrawing reward transaction.

Request withdraw free collateral of custodians

{
"jsonrpc":"1.0",
"method":"createandsendcustodianwithdrawrequest",
"params":[
{{CustodianPrivateKey}},
null,
-1,
0,
{
"Amount": {{WithdrawAmount}},
"PaymentAddress" : {{CustodianIncAddr}},
}
],
"id":1
}

Parameters

  • CustodianPrivateKey (String) : custodian’s private key.
  • CustodianIncAddr (String): custodian’s incognito payment address.
  • WithdrawAmount (String): free collateral amount will be withdrawn.

Response

  • TxID (String): ID of the request withdrawing free collateral transaction.

Get status of request withdraw free collateral

{
"id":1,
"jsonrpc":"1.0",
"method":"getcustodianwithdrawbytxid",
"params":[{
"TxId": {{TxID}}
}]
}

Parameters:

  • TxID (String): ID of requesting withdraw free collateral transaction.

Response

  • Status (Number): 1 - success, 2 - failed.

Get portal state

{
"jsonrpc": "1.0",
"method": "getportalstate",
"params": [{
"BeaconHeight" : {{BeaconHeight}}
}],
"id": 1
}

Parameters

  • BeaconHeight (String): beacon height.

Response

  • WaitingPortingRequests (Array): list of waiting shielding requests.
  • WaitingRedeemRequests (Array): list of waiting unshielding requests.
  • MatchedRedeemRequests (Array): list of matched unshielding requests.
  • CustodianPool (Array): list of custodians.
  • FinalExchangeRatesState (Object): current exchange rates.
  • LiquidationPool (Object): liquidation pool.
  • LockedCollateralForRewards (Object): total locked collateral of each custodians in epoch for calculating portal reward for custodians
19 Likes
How does the Portal work?
Portal API disabled?
Transaction shielding
#2

:sleepy: :exploding_head:

1 Like
#3

Thanks @andrey for sharing this documentation! :white_check_mark:

1 Like
#4

I’m discovering some API to build sth for this community, thank for shares

2 Likes
#5

If ther is any insight of what are you going to build, feel free to share it in the Ideas section :slight_smile: