# Financial Transactions API

## Send DeSo

<mark style="color:green;">`POST`</mark> `/api/v0/send-deso`

Create a Basic transfer transaction. Basic transfer transactions send DeSo from one used to another. Transaction needs to be signed and submitted through `api/v0/submit-transaction` before changes come into effect.

A Basic Transfer transaction sends DeSo from the sender to the receiver.

Endpoint implementation in [backend](https://github.com/deso-protocol/backend/blob/709cbfbc62cf3a0e6d56c393e555fc277c93fb76/routes/transaction.go#L905).

Example usage in frontend:\
&#x20; \- Make request to Send DeSo to get [a preview of the transaction.](https://github.com/deso-protocol/backend/blob/709cbfbc62cf3a0e6d56c393e555fc277c93fb76/routes/transaction.go#L905)\
&#x20; \- Make request to Send DeSo and [sign+submit the transaction.](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/backend-api.service.ts#L667)\
&#x20; \- Use SendDeSo to [transfer DeSo to another user.](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/transfer-deso/transfer-deso.component.ts#L165)

#### Request Body

| Name                                                           | Type            | Description                                                                                                                                                                                                                   |
| -------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SenderPublicKeyBase58Check<mark style="color:red;">\*</mark>   | String          | Public key of the sender                                                                                                                                                                                                      |
| RecipientPublicKeyOrUsername<mark style="color:red;">\*</mark> | String          | Public key or Username of the recipient                                                                                                                                                                                       |
| AmountNanos<mark style="color:red;">\*</mark>                  | int64           | transaction amount in nanos - If less than 0, this will create a max spend transaction that will send all funds from Sender to Receiver                                                                                       |
| MinFeeRateNanosPerKB<mark style="color:red;">\*</mark>         | uint64          | Rate per KB                                                                                                                                                                                                                   |
| TransactionFees                                                | TransactionFee] | <p>Array of</p><p><a data-mention href="/pages/ZMql1yrBqvnDbHsldIax#transactionfee">/pages/ZMql1yrBqvnDbHsldIax#transactionfee</a></p><p>objects that define additional outputs that need to be added to this transaction</p> |

{% tabs %}
{% tab title="200: OK Successfully constructed Send DeSo transaction" %}
{% tabs %}
{% tab title="Sample Response" %}

```json5
{
  "TotalInputNanos": 1999946613,
  "SpendAmountNanos": 1000000000,
  "ChangeAmountNanos": 999946354,
  "FeeNanos": 259,
  "TransactionIDBase58Check": "CbUyAcAiR5C626pSXQ1KCHWxo55FiSsBS66GELxVPPJMT2Q4yjFTA",
  "Transaction": {
    "TxInputs": [ 
      {
        "TxID": [...],
        "Index": 0
      }
    ],
    "TxOutputs": [
      {
        "PublicKey": "Ajl7GoDroKYGRGUK8Twqb/37vziDDK/DSTenXd1EuM5S",
        "AmountNanos": 1000000000
      },
      {
        "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
        "AmountNanos": 999946354
      }
    ],
    "TxnMeta": {},
    "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
    "ExtraData": null,
    "Signature": null,
    "TxnTypeJSON": 2
  },
  "TransactionHex": "025051b0eeda78885641a2340f57b908f475d84ce3b8ce2507815c89e857ef1cce0006caf6e4d44a8575fe235d7d3ffdb1020485526118d3379f5a993a31f5a2823f000202397b1a80eba0a60644650af13c2a6ffdfbbf38830cafc34937a75ddd44b8ce528094ebdc0302aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c45f2f0e7dc0302002102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c450000",
  "TxnHashHex": "df850aef107687e36034e3d298da341fc747d4a663e0a5e98fe3ce05cc10b4be"
}
```

{% endtab %}

{% tab title="Response Field Descriptions" %}
...coming soon! See comments in sample response for descriptions for now.
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Buy Or Sell Creator Coin

<mark style="color:green;">`POST`</mark> `/api/v0/buy-or-sell-creator-coin`

Create a buy/sell creator coin transaction. Transaction needs to be signed and submitted through `api/v0/submit-transaction` before changes come into effect.&#x20;

A buy creator coin transaction locks DeSo in the creator coin of a creator and in return gives the purchaser creator coins.&#x20;

A sell creator coin transaction unlocks an amount of DeSo commensurate with the amount of creator coins sold.

Endpoint implementation in [backend](https://github.com/deso-protocol/backend/blob/709cbfbc62cf3a0e6d56c393e555fc277c93fb76/routes/transaction.go#L1602).

Example usages in frontend:\
&#x20; \- Make request to [Buy Or Sell Creator Coin](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/backend-api.service.ts#L1485)\
&#x20; \- Use BuyOrSellCreatorCoin to get a [preview of purchase/sale of creator coins](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/trade-creator-page/trade-creator-form/trade-creator-form.component.ts#L190)\
&#x20; \- Use BuyOrSellCreatorCoin to [buy or sell creator coins](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/trade-creator-page/trade-creator-preview/trade-creator-preview.component.ts#L89)

#### Request Body

| Name                                                          | Type             | Description                                                                                                                                                                                                                   |
| ------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MinCreatorCoinExpectedNanos                                   | uint64           | <p>Minimum amount of Creator Coins expected when buying creator coins<br><br>only required for buy transactions</p>                                                                                                           |
| MinFeeRateNanosPerKB<mark style="color:red;">\*</mark>        | uint64           | Rate per KB                                                                                                                                                                                                                   |
| CreatorCoinToSellNanos<mark style="color:red;">\*</mark>      | uint64           | <p>Amount of Creator Coin to sell<br><br>only required for sell transactions</p>                                                                                                                                              |
| TransactionFees                                               | TrasactionFee\[] | <p>Array of</p><p><a data-mention href="/pages/ZMql1yrBqvnDbHsldIax#transactionfee">/pages/ZMql1yrBqvnDbHsldIax#transactionfee</a></p><p>objects that define additional outputs that need to be added to this transaction</p> |
| CreatorPublicKeyBase58Check<mark style="color:red;">\*</mark> | String           | Public key of creator whose coin is being purchased                                                                                                                                                                           |
| DeSoToAddNanos<mark style="color:red;">\*</mark>              | uint64           | deprecated                                                                                                                                                                                                                    |
| OperationType<mark style="color:red;">\*</mark>               | String           | "buy" or "sell"                                                                                                                                                                                                               |
| MinDeSoExpectedNanos                                          | uint64           | <p>Minimum DeSo expected to be received when selling creator coins<br><br>only required for sell transactions</p>                                                                                                             |
| DeSoToSellNanos<mark style="color:red;">\*</mark>             | uint64           | <p>Amount of DeSo to spend purchasing creator coins<br><br>only required for buy transactions</p>                                                                                                                             |
| UpdaterPublicKeyBase58Check<mark style="color:red;">\*</mark> | String           | Public key of user purchasing/selling creator coins                                                                                                                                                                           |
| InTutorial                                                    | Boolean          | When true, perform additional checks to ensure user is at the correct point in the tutorial to execute this buy/sell creator coin transaction                                                                                 |

{% tabs %}
{% tab title="200: OK Successfully construct Buy Creator Coin transaction" %}
{% tabs %}
{% tab title="Sample Response" %}

```json5
{
  "ExpectedDeSoReturnedNanos": 0, // Expected amount of DeSo received from the sale. Will always be 0 for buys.
  "ExpectedCreatorCoinReturnedNanos": 1200, // Expected amount of creator coins received from the purchase. Will always be 0 for sales.
  "FounderRewardGeneratedNanos": 9999664686, // Founders reward generated from this purchase. Will always be 0 for sales.
  "SpendAmountNanos": 1000000000,
  "TotalInputNanos": 1933081867,
  "ChangeAmountNanos": 933081602,
  "FeeNanos": 265,
  "Transaction": {
    "TxInputs": [
      {
        "TxID": [... ],
        "Index": 0
      }
    ],
    "TxOutputs": [
      {
        "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
        "AmountNanos": 933081602
      }
    ],
    "TxnMeta": {
      "ProfilePublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF", // Public key of the creator whose coin was purchased in this transaction
      "OperationType": 0, // 0 means buy, 1 means sell
      "DeSoToSellNanos": 1000000000, // Amount of DeSo used to purchase creator coins in this transaction
      "CreatorCoinToSellNanos": 0, // Amount of creator coins sold in this transaction
      "DeSoToAddNanos": 0, // not in use - ignore
      "MinDeSoExpectedNanos": 0, // Minimum DeSo expected from a creator coin sale. This will always be 0 for buys.
      "MinCreatorCoinExpectedNanos": 1000 // Minimum amount of creator coins expected from this purchase. This will always be 0 for sales.
    },
    "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
    "ExtraData": null,
    "Signature": null,
    "TxnTypeJSON": 11
  },
  "TransactionHex": "02acc5b6f137be6a9b49fa1e0b20d0b6c5f2a76618628e1cd34fe8dbb198b627f1001ba3390ffb4817f3d5993ef39fd2fc4cfd75312ba67a7ce2f1d083efa0df2e5e000102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c4582e4f6bc030b2c2102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c45008094ebdc03000000002102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c450000",
  "TxnHashHex": "69f08986184d99833c40d794d3fdd8861c0be602f15e3021ed771e49c6f7771c"
}
```

{% endtab %}

{% tab title="Response Field Descriptions" %}
...coming soon! See comments in sample response for descriptions for now.
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="200: OK Successfully constructed Sell Creator Coin transaction" %}
{% tabs %}
{% tab title="Sample Response" %}

```json5
{
  "ExpectedDeSoReturnedNanos": 270953971, // Expected amount of DeSo received from the sale. Will always be 0 for buys.
  "ExpectedCreatorCoinReturnedNanos": 0, // Expected amount of creator coins received from the purchase. Will always be 0 for sales.
  "FounderRewardGeneratedNanos": 0, // Founder reward generated from this transaction. Will always be 0 for sales.
  "SpendAmountNanos": 0,
  "TotalInputNanos": 933081602,
  "ChangeAmountNanos": 933081367,
  "FeeNanos": 235,
  "Transaction": {
    "TxInputs": [
      {
        "TxID": [...],
        "Index": 0
      }
    ],
    "TxOutputs": [
      {
        "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
        "AmountNanos": 933081367
      }
    ],
    "TxnMeta": {
      "ProfilePublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF", // Public key of the creator whose coin was purchased in this transaction
      "OperationType": 1, // 0 means buy, 1 means sell
      "DeSoToSellNanos": 0, // Amount of DeSo used to purchase creator coins in this transaction
      "CreatorCoinToSellNanos": 1000000000, // Amount of creator coins sold in this transaction
      "DeSoToAddNanos": 0, // Not in use - ignore.
      "MinDeSoExpectedNanos": 203215478, // Minimum DeSo expected from a creator coin sale. This will always be 0 for buys.
      "MinCreatorCoinExpectedNanos": 0 // Minimum amount of creator coins expected from this purchase. This will always be 0 for sales.
    },
    "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
    "ExtraData": null,
    "Signature": null,
    "TxnTypeJSON": 11
  },
  "TransactionHex": "013a58bb26ece8a6abb8f81d4d63359cd42a1602ffc0b99588d70f5278c3e2cb34000102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c4597e2f6bc030b2f2102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c4501008094ebdc0300f6a4f360002102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c450000",
  "TxnHashHex": "c4a8163660bc46f5d6b51f55d0b6b6070d72939eeea13ccae422d78cb255859b"
}
```

{% endtab %}

{% tab title="Response Field Descriptions" %}
...coming soon! See comments in sample response for descriptions for now.
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Transfer Creator Coin

<mark style="color:green;">`POST`</mark> `/api/v0/transfer-creator-coin`

Create a transfer creator coin transaction. Transaction needs to be signed and submitted through `api/v0/submit-transaction` before changes come into effect.&#x20;

Transfer creator coin transactions sends creator coins owned by the sender to the receiver.

Endpoint implementation in [backend](https://github.com/deso-protocol/backend/blob/709cbfbc62cf3a0e6d56c393e555fc277c93fb76/routes/transaction.go#L1860).

Example usages in frontend:\
&#x20; \- Make request to [Transfer Creator Coin](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/backend-api.service.ts#L1543)\
&#x20; \- Use TransferCreatorCoin to get a [preview of a creator coin transfer transaction](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/trade-creator-page/trade-creator-form/trade-creator-form.component.ts#L152).\
&#x20; \- Use TransferCreatorCoin to [construct, sign, and submit a creator coin transfer transaction](https://github.com/deso-protocol/frontend/blob/e006beb72867f6d48a78adb1d126c66144a4298c/src/app/trade-creator-page/trade-creator-preview/trade-creator-preview.component.ts#L167).

#### Request Body

| Name                                                                     | Type             | Description                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SenderPublicKeyBase58Check<mark style="color:red;">\*</mark>             | String           | Public key of user sending creator coins                                                                                                                                                                                      |
| CreatorPublicKeyBase58Check<mark style="color:red;">\*</mark>            | String           | Public key of creator whose coins will be sent                                                                                                                                                                                |
| ReceiverUsernameOrPublicKeyBase58Check<mark style="color:red;">\*</mark> | String           | username or public key of user who will receive creator coins                                                                                                                                                                 |
| CreatorCoinToTransferNanos<mark style="color:red;">\*</mark>             | uint64           | Amount of Creator Coin to transfer                                                                                                                                                                                            |
| MinFeeRateNanosPerKB<mark style="color:red;">\*</mark>                   | uint64           | Rate per KB                                                                                                                                                                                                                   |
| TrasactionFees                                                           | TrasactionFee\[] | <p>Array of</p><p><a data-mention href="/pages/ZMql1yrBqvnDbHsldIax#transactionfee">/pages/ZMql1yrBqvnDbHsldIax#transactionfee</a></p><p>objects that define additional outputs that need to be added to this transaction</p> |

{% tabs %}
{% tab title="200: OK Successfully constructed Transfer Creator Coin transaction" %}
{% tabs %}
{% tab title="Sample Response" %}

```json5
{
  "SpendAmountNanos": 0,
  "TotalInputNanos": 989250936,
  "ChangeAmountNanos": 989250675,
  "FeeNanos": 261,
  "Transaction": {
    "TxInputs": [
      {
        "TxID": [...],
        "Index": 0
      }
    ],
    "TxOutputs": [
      {
        "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
        "AmountNanos": 989250675
      }
    ],
    "TxnMeta": {
      "ProfilePublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF", // Public key of the creator whose coin is being transferred in this transaction
      "CreatorCoinToTransferNanos": 1000000000, // Amount of Creator coins being transferred (in nanos)
      "ReceiverPublicKey": "Ajl7GoDroKYGRGUK8Twqb/37vziDDK/DSTenXd1EuM5S" // Public key of the recipient of the creator coin transfer
    },
    "PublicKey": "Aqo9yNKZ6h5JFN5mSU7T4W7amg1lcZ1SPBqaA8v59gxF",
    "ExtraData": null,
    "Signature": null,
    "TxnTypeJSON": 14
  },
  "TransactionHex": "01f2816e264f381cf153299e0c3cc894ab67687e83b79e55996bdb1c44280aed1d000102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c45f388dbd7030e492102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c458094ebdc032102397b1a80eba0a60644650af13c2a6ffdfbbf38830cafc34937a75ddd44b8ce522102aa3dc8d299ea1e4914de66494ed3e16eda9a0d65719d523c1a9a03cbf9f60c450000",
  "TxnHashHex": "a0e90d5786367855ea2960cd4d8cc3ad81a73c056c7ee62a637ab17aa01320fe"
}
```

{% endtab %}

{% tab title="Response Field Descriptions" %}
...coming soon! See comments in sample response for descriptions for now.
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.deso.org/deso-backend/construct-transactions/financial-transactions-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.