Transfer

Transferring ATOM is a simple process. We will collect:

The account from which ATOM to be transferred, which will sign the transaction.
The address to which ATOM is transferred.
Amount of ATOM to be transferred.
An optional memo to identify the transaction.
An optional gas_limit and gas_price, denominated in ATOM.

In the following guide we will illustrate how to transfer ATOM between accounts.

Create New Transfer Flow

To initiate the transfer process, create a new flow with a POST request to /flows.

URL

https://api.figment.io/flows

Request

protocol* : string Protocol this flow operates on (ex. cosmos).
network* : string Network this flow operates on (ex. testnet).
operation* : string The operation to perform (ex. transfer).

JSON

{
  "protocol": "cosmos",
  "network": "testnet",
  "operation": "transfer"
}

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
actions : array It includes the name & inputs of all next possible actions.
create_transfer_tx— Use this action to transfer ATOM.
from_account_address : The address from which ATOM will be transferred.
- to_account_address : The address to which ATOM will be transferred.
- amount : The amount of ATOM to be transferred.
- memo : an optional message to record on-chain with your transfer.
- gas_limit: The total amount of gas you're willing to let this transaction consume.
If you do not include this, we'll use a Cosmos library to select a good default for you.
- gas_price: How many ATOM you're willing to pay per unit of gas consumed by this transaction.
If you do not include this, we'll use a Cosmos library to select a good default for you.
- pubkey : Pubkey value will be retrieved from the chain but if you're using a fresh account (that does not have any outgoing activity) then this information is not available and it requires the user to pass it.
data : object Flow & transaction data.

JSON

{
  "id": "1ff5d5ce-9716-441f-a197-5c264e16965b",
  "operation": "transfer",
  "state": "initialized",
  "actions": [
    {
      "name": "create_transfer_tx",
      "inputs": [
        {
          "name": "from_account_address",
          "display": "From Account Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "to_account_address",
          "display": "To Account Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "amount",
          "display": "Amount",
          "description": "in ATOM",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "memo",
          "display": "Memo",
          "description": "",
          "type": "string",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "in ATOM",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "in ATOM",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "pubkey",
          "display": "Pubkey",
          "description": "Value will be retrieved from the chain if available",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "from_account_address": null,
    "to_account_address": null,
    "amount": null,
    "gas_price": null,
    "gas_limit": null,
    "memo": null,
    "transfer_transaction": null,
    "pubkey": null
  },
  "protocol": "cosmos",
  "network": "testnet",
  "created_at": "2023-02-28T11:46:05.097Z",
  "updated_at": "2023-02-28T11:46:05.097Z"
}

Submit Transfer Data

After creating the new transfer flow, we need to submit the transfer data.

After collecting the required inputs as mentioned below, send a PUT request to /flows/[:flow_id]/next to proceed to the next step.

URL

https://api.figment.io/flows/[:flow_id]/next

Request

name* : create_transfer_tx.
inputs* : object
- from_account_address* : string The address from which ATOM will be transferred.
- to_account_address* : string The address to which ATOM will be transferred.
- amount* : number The amount of ATOM to be transferred.
- memo : string A message to record on-chain with your transfer.
- gas_limit : number The total amount of gas you're willing to let this transaction consume.
- gas_price : number How many ATOM you're willing to pay per unit of gas consumed by this transaction.
- pubkey : string Required only if you're using a fresh account (that does not have any outgoing activity) else optional.

JSON

{
  "name": "create_transfer_tx",
  "inputs": {
    "from_account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "to_account_address": "cosmos1vxhllask0nynh20htyfkpkfthy7k3395kz8y3c",
    "amount": 0.1
  }
}

Response

refresh_transfer_tx : If you need to get a fresh version of the transaction payload (i.e., the nonce has increased).
- sign_transfer_tx : Submit a signed transaction payload or an array of signatures to continue the flow.
- confirm_transfer_tx_by_hash : Submit a previously completed transaction hash to continue the flow.
data : object Flow & transaction data.

JSON

{
  "id": "1ff5d5ce-9716-441f-a197-5c264e16965b",
  "operation": "transfer",
  "state": "transfer_tx_signature",
  "actions": [
    {
      "name": "refresh_transfer_tx",
      "inputs": [
        {
          "name": "from_account_address",
          "display": "From Account Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
        },
        {
          "name": "to_account_address",
          "display": "To Account Address",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "cosmos1vxhllask0nynh20htyfkpkfthy7k3395kz8y3c"
        },
        {
          "name": "amount",
          "display": "Amount",
          "description": "in ATOM",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": "0.1"
        },
        {
          "name": "memo",
          "display": "Memo",
          "description": "",
          "type": "string",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_price",
          "display": "Gas Price",
          "description": "in ATOM",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "gas_limit",
          "display": "Gas Limit",
          "description": "in ATOM",
          "type": "decimal",
          "validations": [],
          "array": false,
          "default_value": null
        },
        {
          "name": "pubkey",
          "display": "Pubkey",
          "description": "Value will be retrieved from the chain if available",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
        }
      ]
    },
    {
      "name": "sign_transfer_tx",
      "inputs": [
        {
          "name": "transaction_payload",
          "display": "Transaction Payload",
          "description": "",
          "type": "signed_transaction",
          "validations": [
            {
              "type": "sign_payload",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null,
          "signers": [
            "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
          ],
          "transaction_payload": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e62616e6b2e763162657461312e4d736753656e64222c2276616c7565223a7b2266726f6d41646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c22746f41646472657373223a22636f736d6f73317678686c6c61736b306e796e683230687479666b706b66746879376b333339356b7a38793363222c22616d6f756e74223a5b7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a22313030303030227d5d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2231393637222c2264656e6f6d223a227561746f6d227d5d2c22676173223a223738363535227d2c226d656d6f223a22227d"
        },
        {
          "name": "signatures",
          "display": "Signatures",
          "description": "",
          "type": "array_of_signatures",
          "validations": [],
          "array": true,
          "default_value": null,
          "element_type": "signature_data",
          "signers": [
            "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl"
          ],
          "transaction_payload": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e62616e6b2e763162657461312e4d736753656e64222c2276616c7565223a7b2266726f6d41646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c22746f41646472657373223a22636f736d6f73317678686c6c61736b306e796e683230687479666b706b66746879376b333339356b7a38793363222c22616d6f756e74223a5b7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a22313030303030227d5d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2231393637222c2264656e6f6d223a227561746f6d227d5d2c22676173223a223738363535227d2c226d656d6f223a22227d",
          "signing_payload": "6c90440d3d80a938ec972ec744d87c0f7ecbb155e903737db885e1b71b321e9c",
          "inputs": [
            {
              "name": "account_address",
              "display": "Account Address",
              "description": "",
              "type": "string",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            },
            {
              "name": "signature",
              "display": "Signature",
              "description": "",
              "type": "string",
              "validations": [
                {
                  "type": "presence",
                  "options": {}
                }
              ],
              "array": false,
              "default_value": null
            }
          ]
        }
      ]
    },
    {
      "name": "confirm_transfer_tx_by_hash",
      "inputs": [
        {
          "name": "hash",
          "display": "Hash",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "block_number",
          "display": "Block Number",
          "description": "",
          "type": "integer",
          "validations": [],
          "array": false,
          "default_value": null
        }
      ]
    }
  ],
  "data": {
    "from_account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "to_account_address": "cosmos1vxhllask0nynh20htyfkpkfthy7k3395kz8y3c",
    "amount": "0.1",
    "gas_price": null,
    "gas_limit": null,
    "memo": "",
    "transfer_transaction": {
      "raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e62616e6b2e763162657461312e4d736753656e64222c2276616c7565223a7b2266726f6d41646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c22746f41646472657373223a22636f736d6f73317678686c6c61736b306e796e683230687479666b706b66746879376b333339356b7a38793363222c22616d6f756e74223a5b7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a22313030303030227d5d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2231393637222c2264656e6f6d223a227561746f6d227d5d2c22676173223a223738363535227d2c226d656d6f223a22227d",
      "signing_payload": "6c90440d3d80a938ec972ec744d87c0f7ecbb155e903737db885e1b71b321e9c",
      "signed": null,
      "hash": null,
      "status": null,
      "error": null,
      "signatures": null,
      "block_time": null
    },
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
  },
  "protocol": "cosmos",
  "network": "testnet",
  "created_at": "2023-02-28T11:46:05.097Z",
  "updated_at": "2023-02-28T11:51:00.312Z"
}

Submit Signed Transfer Transaction for Broadcast

Before broadcasting the transaction, you must sign the transaction_payload you received in the previous step. After signing the transaction, send a PUT request to /flows/[:flow_id]/next and the Staking API will broadcast the transaction to the network.

URL

https://api.figment.io/flows/[:flow_id]/next

Request

name* : sign_transfer_tx
inputs* : object
- transaction_payload* : Signed transaction payload from the previous step's response.
- signatures : array of object The signatures array can be used instead of sending a transaction payload when the signing keys are kept in a custodial solution, such as Fireblocks.

JSON

{
  "name": "sign_transfer_tx",
  "inputs": {
    "transaction_payload": "0a92010a8f010a1c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e64126f0a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c122d636f736d6f73317678686c6c61736b306e796e683230687479666b706b66746879376b333339356b7a387933631a0f0a057561746f6d120631303030303012670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180a12130a0d0a057561746f6d12043139363710bfe6041a408c4cc00ff79d497f98baa639ae673d84d21cda8d82109a93857c7d99cb016881297c6fe2d3b4a9e7328e7f242cb3f0f5abff668a8bde09b7fb8c051c4d287d87"
  }
}

Response

id : string ID of the flow.
operation : string The Staking API operation being performed by this flow.
state : string The current state of the flow.
transfer_tx_broadcasting : Transaction has been broadcast and is waiting for confirmation.
- completed : Transaction has been confirmed and the transfer is complete.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.

JSON

{
  "id": "1ff5d5ce-9716-441f-a197-5c264e16965b",
  "operation": "transfer",
  "state": "transfer_tx_broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2023-02-28T11:52:51.637Z",
      "inputs": []
    }
  ],
  "data": {
    "from_account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
    "to_account_address": "cosmos1vxhllask0nynh20htyfkpkfthy7k3395kz8y3c",
    "amount": "0.1",
    "gas_price": null,
    "gas_limit": null,
    "memo": "",
    "transfer_transaction": {
      "raw": "7b226d65737361676573223a5b7b227479706555726c223a222f636f736d6f732e62616e6b2e763162657461312e4d736753656e64222c2276616c7565223a7b2266726f6d41646472657373223a22636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c222c22746f41646472657373223a22636f736d6f73317678686c6c61736b306e796e683230687479666b706b66746879376b333339356b7a38793363222c22616d6f756e74223a5b7b2264656e6f6d223a227561746f6d222c22616d6f756e74223a22313030303030227d5d7d7d5d2c22666565223a7b22616d6f756e74223a5b7b22616d6f756e74223a2231393637222c2264656e6f6d223a227561746f6d227d5d2c22676173223a223738363535227d2c226d656d6f223a22227d",
      "signing_payload": "6c90440d3d80a938ec972ec744d87c0f7ecbb155e903737db885e1b71b321e9c",
      "signed": "0a92010a8f010a1c2f636f736d6f732e62616e6b2e763162657461312e4d736753656e64126f0a2d636f736d6f733175383575706b3276377072363567307776323937367a6c6575367638716a6c39717072767a6c122d636f736d6f73317678686c6c61736b306e796e683230687479666b706b66746879376b333339356b7a387933631a0f0a057561746f6d120631303030303012670a500a460a1f2f636f736d6f732e63727970746f2e736563703235366b312e5075624b657912230a2102db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe23512040a020801180a12130a0d0a057561746f6d12043139363710bfe6041a408c4cc00ff79d497f98baa639ae673d84d21cda8d82109a93857c7d99cb016881297c6fe2d3b4a9e7328e7f242cb3f0f5abff668a8bde09b7fb8c051c4d287d87",
      "hash": "01A6F459A7585A17285ADB953093F6D8EE47A67B4844E39FE192A0AE2E3B71E1",
      "status": null,
      "error": null,
      "signatures": [
        {
          "account_address": "cosmos1u85upk2v7pr65g0wv2976zleu6v8qjl9qprvzl",
          "signature": ""
        }
      ],
      "block_time": null
    },
    "pubkey": "02db33d72ee215f1a61e5f4ffa098b9325cc1da6f5c3557974ad0f21a5ec9fe235"
  },
  "protocol": "cosmos",
  "network": "testnet",
  "created_at": "2023-02-28T11:46:05.097Z",
  "updated_at": "2023-02-28T11:51:50.689Z"
}

Get Transfer Flow Status

To get the current state of the existing flow, send a GET request to /flows/[:flow_id] using the flow ID from the previous step.

URL

https://api.figment.io/flows/[:flow_id]

Request

None

Response

transfer_tx_broadcasting : Transaction has been broadcast and is waiting for confirmation.
- completed : Transaction has been confirmed and the delegation is complete.
actions : array It includes the name & inputs of all next possible actions.
data : object Flow & transaction data.