4️⃣4️⃣ Transactions: API

Transactions are the building material of every blockchain.

Transactions allow users to submit data to the blockchain which allows user to perform actions such as transferring DeSo, creating posts and profiles, and minting NFTs.

Transactions have three steps in their lifecycle

1. Construct: The first step for a developer is to interact with the DeSo Backend API through a transaction construction endpoint to get an unsigned user transaction. Social Transactions API, NFT Transactions API, Financial Transactions API, and Derived Keys Transaction API explain the endpoints that will get you an unsigned transaction.

2. Sign: The developer will then take the output TransactionHex from the construct step's response, which encodes the user transaction, and signs it using DeSo Identity. You can read about signing transactions in thesign section of the Endpoints documentation.

3. Broadcast: The signed transaction will be sent through the /api/v0/submit-transaction by the developer so that it can be added to the blockchain ledger. The Submit a transaction submit explains how this endpoint works.

You can read more about Transactions in this section of the Identity documentation.

Submit a transaction

POST /api/v0/submit-transaction

Submit a signed transaction to DeSo blockchain.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Submit Transaction - Use Submit Transaction in conjunction with signing transaction

Request Body

Name	Type	Description
TransactionHex*	String	Hex of transaction

200: OK

Sample Response

{
    "Transaction": {
      "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF", // public key of the transactor
      "TxnTypeJSON": 5, // Integer representing transaction type
      "ExtraData": { // Arbitrary key value map providing metadata about the transaction
        "key": "value"
      },
      "Signature": {
        "R": 981237981749831749879848321, // R attribute of signature
        "S": 843174832748124, // S attribute of signature
      },
      "TxInputs": [{
        "Index": 0, // Index within transaction where the unspent output occurs
        "TxID": [1, 2, 3, ...] // 32 byte transaction id where unspent output occurs 
      }],
      "TxOutputs": [{ 
        "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF", // Public key receiving the output
        "AmountNanos": 912739 // Amount of DeSo in the output
      }],
      "TxnMeta": { // Transaction metadata. more details explaining TxnMeta for each transaction type coming soon. 
      ...
      }
    },
    "TxnHashHex": "0f40a5fc7eb991cea55ebece1ec21ee5fb1c4bba537bb76643ee1d31f617bb56",
    "PostEntryResponse": <PostEntryResponse>, // If transaction is a Submit post transaction, include the PostEntryResponse that was created as a result of the transaction.
}

Response Field Descriptions

Name	Type	Description
Transaction	Transaction object	transaction object that was broadcast to the DeSo blockchain
PublicKey	string	Attribute of transaction Public key of transactor
TxnTypeJSON	integer	Attribute of transaction Number representing transaction type
ExtraData	map[string]string	Attribute of transaction Arbitrary key value map providing metadata about the transaction
Signature	{ R: integer, S: integer }	Attribute of transaction Signature of transactoin
TxInputs	Array of transaction iputs [{ Index: integer, TxId: integer[] }]	Attribute of transaction Each element represents an input (DeSo being used) in the transaction.
TxOutputs	Array of transaction outputs [{ PublicKey: string, AmountNanos: integer }]	Attribute of transaction Each element represents an output (DeSo being received) in the transaction
TxnMeta	Transaction Metadata object	Attribute of transaction Transaction Metadata descriptions coming soon. Each transaction type has its own transaction metadata object structure.
TxnHashHex	String	Hex of transaction hash broadcasted to the DeSo blockchain
PostEntryResponse	PostEntryResponse	If a transaction is a submit post transaction, the PostEntryResponse that was created by the transaction is included

400: Bad Request Unable to broadcast transaction to network

Get Transaction

POST /api/v0/get-txn

Check if transaction is currently in mempool. This is particularly useful if you need to wait for a transaction to be broadcasted before submitting a subsequent transaction.

Endpoint implementation in backend.

Example usages in frontend: - Make request to Get Txn - Use Get Txn to see if a transaction has been broadcast to the network

Request Body

Name	Type	Description
TransactionHashHex*	Strng	Hex of Transaction hash that we want to check made it to the mempool

200: OK undefined

Sample Response

{
    "TxnFound": true
}

Response Field Descriptions

Name	Type	Description
TxnFound	boolean	If true, the transaction is currently in the mempool

400: Bad Request

Append Extra Data

POST /api/v0/append-extra-data

Append custom ExtraData for a given transaction hex. This endpoint is typically used when signing with a derived key.

Note: If you will be using this endpoint, you will need to increase MinFeeRateNanosPerKB to 1500 when using a transaction construction endpoint.

Endpoint implementation in backend

Request Body

Name	Type	Description
TransactionHex*	String	The hex of the transaction on which extra data will be appended.
ExtraData*	map[string]string	Arbitrary key value map that will be merged with any extra data decoded from TransactionHex. Keys from this map will overwrite keys that were decoded from TransactionHex

400: Bad Request

{
    // Response
}

200: OK Hex of transaction with extra data appended

Sample Response

{
  "TransactionHex": "sometransactionhex"
}

Response Field Descriptions

Name	Type	Description
TransactionHex	string	hex of transaction with extra data appended

Get Transaction Spending

POST /api/v0/get-transaction-spending

Calculates the total transaction spending by subtracting transaction output to sender from transaction inputs. This allows a convenient way to display to users how much they will spend if they submit a given transaction to the network.

Endpoint implementation in backend

Example usages in identity: - Make request to Get Transaction Spending - Use Get Transaction Spending to show user total spending of transaction

Request Body

Name	Type	Description
TransactionHex*	String	The hex of the transaction on which extra data will be appended.

200: OK Total amount spent in the transaction

Sample Response

{
  "TotalSpendingNanos": 1000823987
}

Response Field Descriptions

Name	Type	Description
TotalSpendingNanos	Integer	Total amount spent by the transactor in this transaction