cosmos-sdk/docs/spec/light/api.md

Cosmos Hub (Gaia) LCD API

This document describes the API that is exposed by the specific LCD implementation of the Cosmos Hub (Gaia). Those APIs are exposed by a REST server and can easily be accessed over HTTP/WS(websocket) connections.

The complete API is comprised of the sub-APIs of different modules. The modules in the Cosmos Hub (Gaia) API are:

• ICS0 (TendermintAPI)
• ICS1 (KeyAPI)
• ICS20 (TokenAPI)
• ICS21 (StakingAPI) - not yet implemented
• ICS22 (GovernanceAPI) - not yet implemented

Error messages my change and should be only used for display purposes. Error messages should not be used for determining the error type.

ICS0 - TendermintAPI - not yet implemented

Exposes the same functionality as the Tendermint RPC from a full node. It aims to have a very similar API.

/broadcast_tx_sync - POST

url: /broadcast_tx_sync

Functionality: Submit a signed transaction and wait for it to be committed.

Parameters:

Parameter	Type	Default	Required	Description
transaction	string	null	true	signed tx bytes

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
	"code": 0,
	"hash": "0D33F2F03A5234F38706E43004489E061AC40A2E",
	"data": "",
	"log": ""
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not submit the transaction synchronously.",
    "result": {}
}

/broadcast_tx_async - POST

url: /broadcast_tx_async

Functionality: Submit a signed transaction asynchronously.

Parameters:

Parameter	Type	Default	Required	Description
transaction	string	null	true	signed tx bytes

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
		"code": 0,
		"hash": "E39AAB7A537ABAA237831742DCE1117F187C3C52",
		"data": "",
		"log": ""
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not submit the transaction asynchronously.",
    "result": {}
}

ICS1 - KeyAPI

This API exposes all functionality needed for key creation, signing and management.

/keys - GET

url: /keys

Functionality: Gets a list of all the keys.

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
        "keys": [
           {
                "name": "monkey",
                "address": "cosmosaccaddr1fedh326uxqlxs8ph9ej7cf854gz7fd5zlym5pd",
                "pub_key": "cosmosaccpub1zcjduc3q8s8ha96ry4xc5xvjp9tr9w9p0e5lk5y0rpjs5epsfxs4wmf72x3shvus0t"
            },
            {
                "name": "test",
                "address": "cosmosaccaddr1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
                "pub_key": "cosmosaccpub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
            }
        ],
        "block_height": 5241
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error":"Could not retrieve the keys.",
    "result":{}
}

/keys/recover - POST

url: /keys/recover

Functionality: Recover your key from seed and persist it encrypted with the password.

Parameter:

Parameter	Type	Default	Required	Description
name	string	null	true	name of key
password	string	null	true	password of key
seed	string	null	true	seed of key

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
        "address":BD607C37147656A507A5A521AA9446EB72B2C907
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not recover the key.",
    "result": {}
}

/keys/create - POST

url: /keys/create

Functionality: Create a new key.

Parameter:

Parameter	Type	Default	Required	Description
name	string	null	true	name of key
password	string	null	true	password of key

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
        "seed":crime carpet recycle erase simple prepare moral dentist fee cause pitch trigger when velvet animal abandon
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not create new key.",
    "result": {}
}

/keys/{name} - GET

url: /keys/{name}

Functionality: Get the information for the specified key.

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
        "name": "test",
            "address": "cosmosaccaddr1thlqhjqw78zvcy0ua4ldj9gnazqzavyw4eske2",
            "pub_key": "cosmosaccpub1zcjduc3qyx6hlf825jcnj39adpkaxjer95q7yvy25yhfj3dmqy2ctev0rxmse9cuak"
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not find information on the specified key.",
    "result": {}
}

/keys/{name} - PUT

url: /keys/{name}

Functionality: Change the encryption password for the specified key.

Parameters:

Parameter	Type	Default	Required	Description
old_password	string	null	true	old password
new_password	string	null	true	new password

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {}
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not update the specified key.",
    "result": {}
}

/keys/{name} - DELETE

url: /keys/{name}

Functionality: Delete the specified key.

Parameters:

Parameter	Type	Default	Required	Description
password	string	null	true	password of key

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {}
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not delete the specified key.",
    "result": {}
}

ICS20 - TokenAPI

The TokenAPI exposes all functionality needed to query account balances and send transactions.

/bank/balance/{account} - GET

url: /bank/balance/{account}

Functionality: Query the specified account.

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
        "atom": 1000,
        "photon": 500,
        "ether": 20
    }
}

Returns on error:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not find any balance for the specified account.",
    "result": {}
}

/bank/create_transfer - POST

url: /bank/create_transfer

Functionality: Create a transfer in the bank module.

Parameters:

Parameter	Type	Default	Required	Description
sender	string	null	true	Address of sender
receiver	string	null	true	address of receiver
chain_id	string	null	true	chain id
amount	int	null	true	amount of the token
denomonation	string	null	true	denomonation of the token

Returns on success:

{
    "rest api": "2.0",
    "code":200,
    "error": "",
    "result": {
     "transaction": "TODO:<JSON sign bytes for the transaction>"
    }
}

Returns on failure:

{
    "rest api": "2.0",
    "code":500,
    "error": "Could not create the transaction.",
    "result": {}
}