Documentation
P2P.org
Start typing to search…

Cosmos

Unified API + Cosmos Integration Workflow

In the following guide, the integration process for the cosmos chain is covered. The Cosmos integration aligns with the general Unified API process but with network-specific parameters.

Get an authentication token to start using the Unified API.

Request examples are provided using cURL.

To check the integration guides for other chains, refer to the Networks Supported section.

📘

Key Cosmos-specific details

  • chain — always set to cosmos for Cosmos-related requests.
  • network — environment in which the transaction is processed: cosmoshub-4 only.
  • stakerAddress — account address initiating staking, unstaking or withdrawal transactions.
  • amount — amount of tokens in ATOM (in uATOM internally).

Staking Flow

1. Create Stake Request

Send a POST request to /api/v1/unified/staking/stake.

Example request:

curl --request POST \
     --url https://api.p2p.org/api/v1/unified/staking/stake \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "cosmos",
    "network": "cosmoshub-4",
    "stakerAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
    "amount": "0.0042"
}'
  • chain — blockchain network, always set to cosmos for Cosmos-related requests.
  • network — environment in which the transaction is processed: cosmoshub-4 only.
  • stakerAddress — account address initiating the staking transaction.
  • amount — amount of tokens to stake in ATOM.

Example response:

{
  "error": null,
  "result": {
    "amount": 0.0042,
    "stakerAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
    "unsignedTransactionData": {
      "messages": [
        {
          "typeUrl": "/cosmos.staking.v1beta1.MsgUndelegate",
          "value": {
            "delegatorAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
            "validatorAddress": "cosmosvaloper132juzk0gdmwuxvx4phug7m3ymyatxlh9734g4w",
            "amount": {
              "denom": "uatom",
              "amount": "4000"
            }
          }
        }
      ],
      "fee": {
        "amount": [
          {
            "amount": "14672",
            "denom": "uatom"
          }
        ],
        "gas": "586847"
      },
      "memo": "",
      "encodedBody": "0a9d010a252f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c656761746512740a2d636f736d6f7331746d7070363333766633376436376c716e797578773561386c76766461716b736130783061711234636f736d6f7376616c6f7065723133326a757a6b3067646d77757876783470687567376d33796d796174786c68393733346734771a0d0a057561746f6d120434303030",
      "encodedAuthInfo": "0a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a21030b155e1a5773bfae8759223f986febc4094328de05f79924363cc6887ffd9aed12040a020801180212140a0e0a057561746f6d1205313436373210dfe823",
      "messageHash": "cd63647dbc65aaae6a6fd925df121ffde799eadb665784a3a465993207024ec5"
    },
    "createdAt": "2025-03-31T08:02:36.633Z",
    "extraData": {
      "currency": "atom",
      "validatorAddress": "cosmosvaloper132juzk0gdmwuxvx4phug7m3ymyatxlh9734g4w",
      "rewardDestinationAddress": "cosmos1k664uhuyzpwss3y45fc0zzamcr3ujpeww33ruu"
    }
  }
}
  • amount — amount of tokens to stake in ATOM.
  • stakerAddress — account address initiating the staking transaction.
  • unsignedTransactionData — unsigned transaction in Base64 encrypted format. The object contains the list of data fields to be used to construct the staking transaction.
    • messages — transaction messages for each staking operation.
      • typeUrl — Cosmos network operation type.
      • value — message payload, encoded in the hexadecimal format.
        • delegatorAddress — account address initiating the delegation.
        • validatorAddress — validator address receiving the delegation.
        • amount.amount — amount of tokens to stake.
        • amount.denom — currency of tokens, always set to uatom (1 ATOM = 10⁻⁶ uATOM).
    • fee — fee charged for processing the transaction.
      • amount — amount of tokens.
        • denom — currency of tokens: atom, uatom, or matom.
        • gas — amount of gas spent for the transaction.
    • memo — arbitrary text data to add to the transactions.
    • encodedBody — processable transaction data encoded in the hexadecimal format.
    • encodedAuthInfo — authorization data, including fee, encoded in the hexadecimal format.
    • messageHash — hash of the transaction message.
  • createdAt — timestamp of the transaction in ISO 8601 format.
  • extraData — additional transaction details:
    • currency — ATOM, Cosmos native staking token.
    • validatorAddress — validator address to which tokens are delegated.
    • rewardDestinationAddress — account address receiving the staking rewards.

2. Sign and Send Transaction

Use unsignedTransactionData to sign the transaction using the Cosmos-specific signing logic.

To broadcast the signed transaction to the Cosmos network, send a POST request to /api/v1/unified/transaction/broadcast.

Example request:

curl --request POST \
     --url https://api.p2p.org/api/v1/unified/transaction/broadcast \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "cosmos",
    "network": "cosmoshub-4",
    "stakerAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
    "signedTransaction": "0aa6010aa3010a252f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c6567617465127a0a2f63656c657374696131746d7070363333766633376436376c716e797578773561386c76766461716b737639686c3864123663656c657374696176616c6f70657231616d6d30756d7871787877386a32713630783738787333327330383936303673646d767839321a0f0a047574696112073130303030303012660a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a21030b155e1a5773bfae8759223f986febc4094328de05f79924363cc6887ffd9aed12040a020801180112120a0c0a047574696112043439363010f08d0c1a40b704538dadc6a1de4d7c881a1454ca75245f2651b35347062b9246543d2f7eb016bc897eeeeac37702ddaf6697d92b75cd659b4be46103a6da0cf3407dc0d73b"
}'
  • chain — blockchain network.
  • network — environment in which the transaction is processed.
  • stakerAddress — Cosmos account address initiating the staking transaction.
  • signedTransaction — signed transaction in Base64 encrypted format, which contains all transaction details (e.g., accounts, instructions, and signatures) required to broadcast the transaction to the network.

Example response:

{
    "error": null,
    "result": {
        "status": "success",
        "blockId": 18575267,
        "fee": 0.005952,
        "gas": {
            "used": 202947,
            "wanted": 238047
        },
        "transactionHash": "ADD7B2791E1959075D1836D4BCC71ED256CCD724459F9BD8862D85E205075D47"
    }
}
  • status — transaction status: pending, success, or failed.
  • extraData — additional transaction details:
    • blockId — unique identifier of the block in which the transaction has been included.
    • fee — total fee in ATOM charged for processing the transaction.
    • gas — computational effort required to execute the transaction, measured in gas units.
      • used — amount of gas spent for the transaction.
      • wanted — maximum gas limit available to consume for the transaction.
    • transactionHash — hash of the transaction.

Unstaking Flow

1. Create Unstaking Request

Send a POST request to /api/v1/unified/staking/unstake.

Example request:

curl --request POST \
     --url https://api.p2p.org/api/v1/unified/staking/unstake \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>' \
     --data '{
    "chain": "cosmos",
    "network": "cosmoshub-4",
    "stakerAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
    "extra": {
        "amount": 0.0042
    }
}'
  • chain — blockchain network.
  • network — environment in which the transaction is processed.
  • stakerAddress — account address initiated the staking transaction.
  • extra — additional request parameters:
    • amount — amount of tokens to unstake in ATOM.

Example response:

{
  "error": null,
  "result": {
    "amount": 0.0042,
    "stakerAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
    "unsignedTransactionData": {
      "messages": [
        {
          "typeUrl": "/cosmos.staking.v1beta1.MsgUndelegate",
          "value": {
            "delegatorAddress": "cosmos1tmpp633vf37d67lqnyuxw5a8lvvdaqksa0x0aq",
            "validatorAddress": "cosmosvaloper132juzk0gdmwuxvx4phug7m3ymyatxlh9734g4w",
            "amount": {
              "denom": "uatom",
              "amount": "4000"
            }
          }
        }
      ],
      "fee": {
        "amount": [
          {
            "amount": "14672",
            "denom": "uatom"
          }
        ],
        "gas": "586847"
      },
      "memo": "",
      "encodedBody": "0a9d010a252f636f736d6f732e7374616b696e672e763162657461312e4d7367556e64656c656761746512740a2d636f736d6f7331746d7070363333766633376436376c716e797578773561386c76766461716b736130783061711234636f736d6f7376616c6f7065723133326a757a6b3067646d77757876783470687567376d33796d796174786c68393733346734771a0d0a057561746f6d120434303030",
      "encodedAuthInfo": "0a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a21030b155e1a5773bfae8759223f986febc4094328de05f79924363cc6887ffd9aed12040a020801180212140a0e0a057561746f6d1205313436373210dfe823",
      "messageHash": "cd63647dbc65aaae6a6fd925df121ffde799eadb665784a3a465993207024ec5"
    },
    "createdAt": "2025-03-27T07:16:58.337Z",
    "extraData": {
      "currency": "atom",
      "validatorAddress": "cosmosvaloper132juzk0gdmwuxvx4phug7m3ymyatxlh9734g4w",
      "rewardDestinationAddress": "cosmos1y9wefmlpm0djkt8sseeveke0httfukg2a60g0r"
    }
  }
}
  • amount — amount of tokens to unstake in ATOM.
  • stakerAddress — staking account address keeping the staked tokens.
  • unsignedTransactionData — unsigned transaction in Base64 encrypted format. The object contains the list of data fields to be used to construct the unstaking transaction.
    • messages — transaction messages for each staking operation.
      • typeUrl — Cosmos network operation type.
      • delegatorAddress — delegator address.
      • validatorAddress — validator address.
      • amount — amount of tokens to unstake.
      • denom — currency of tokens, always set to uatom (1 ATOM = 10⁻⁶ uATOM).
    • fee — fee charged for processing the transaction.
      • amount — amount of tokens.
      • denom — currency of tokens: atom, uatom, or matom.
      • gas — amount of gas spent for the transaction.
    • memo — arbitrary text data to add to the transactions.
    • encodedBody — processable transaction data encoded in the hexadecimal format.
    • encodedAuthInfo — authorization data, including fee, encoded in the hexadecimal format.
    • messageHash — hash of the transaction.
  • createdAt — timestamp of the transaction in the ISO 8601 format.
  • extraData — additional transaction details:
    • amount — amount of tokens to unstake in ATOM.
    • currency — currency of tokens: atom, uatom, or matom.
    • validatorAddress — validator address from which tokens are delegated.
    • rewardDestinationAddress — rewards destination account address.

2. Sign and Send Transaction

Use unsignedTransactionData to sign and send the transaction following the Cosmos-specific signing logic.

What's Next?

Updated 12 days ago