2018-10-04 21:55:03 +03:00
# Wallet Owner API Documentation
## Table of Contents
1. [Wallet Owner Endpoint ](#wallet-owner-endpoint )
1. [GET Retrieve Outputs ](#get-retrieve-outputs )
1. [GET Retrieve Summary Info ](#get-retrieve-summary-info )
1. [GET Node Height ](#get-node-height )
1. [GET Retrieve Txs ](#get-retrieve-txs )
2019-01-10 17:09:56 +03:00
1. [GET Retrieve Stored Tx ](#get-retrieve-stored-tx )
2018-10-04 21:55:03 +03:00
1. [POST Issue Send Tx ](#post-issue-send-tx )
1. [POST Finalize Tx ](#post-finalize-tx )
1. [POST Cancel Tx ](#post-cancel-tx )
2018-11-28 19:52:55 +03:00
1. [POST Post Tx ](#post-post-tx )
2019-02-12 16:39:43 +03:00
1. [POST Repost Tx ](#post-repost-tx )
2018-10-04 21:55:03 +03:00
1. [POST Issue Burn Tx ](#post-issue-burn-tx )
2019-01-07 13:00:52 +03:00
1. [Adding Foreign API Endpoints ](#add-foreign-api-endpoints )
2018-10-04 21:55:03 +03:00
## Wallet Owner Endpoint
### GET Retrieve Outputs
Attempt to update and retrieve outputs.
* **URL**
2018-10-17 17:51:50 +03:00
* /v1/wallet/owner/retrieve_outputs
* /v1/wallet/owner/retrieve_outputs?refresh& show_spent& tx_id=x& tx_id=y
2018-10-04 21:55:03 +03:00
* **Method:**
`GET`
* **URL Params**
**Optional:**
`refresh` to refresh from node
`show_spent` to show spent outputs
`tx_id=[number]` to retrieve only the specified output
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:---------------------|:---------|:---------------------------------------------------------------|
| | bool | Whether it was refreshed from node |
| - | []object | Array |
| - - | []object | Array of Output Data |
| - - - | object | Output Data |
| - - - - root_key_id | string | Root key_id that the key for this output is derived from |
| - - - - key_id | string | Derived key for this output |
| - - - - n_child | number | How many derivations down from the root key |
| - - - - value | number | Value of the output, necessary to rebuild the commitment |
| - - - - status | string | Current status of the output |
| - - - - height | number | Height of the output |
| - - - - lock_height | number | Height we are locked until |
| - - - - is_coinbase | bool | Is this a coinbase output? Is it subject to coinbase locktime? |
| - - - - tx_log_entry | number | Optional corresponding internal entry in tx entry log |
| - - - | []number | Pedersen Commitment |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/retrieve_outputs?refresh& id=3",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Retrieve Summary Info
Retrieve summary info for wallet.
* **URL**
2018-10-17 17:51:50 +03:00
* /v1/wallet/owner/retrieve_summary_info
* /v1/wallet/owner/retrieve_summary_info?refresh
2018-10-04 21:55:03 +03:00
* **Method:**
`GET`
* **URL Params**
**Optional:**
`refresh` to refresh from node
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:----------------------------------|:---------|:----------------------------------------|
| | bool | Whether it was refreshed from node |
| - | object | Wallet information |
| - - last_confirmed_height | number | Height from which info was taken |
| - - total | number | Total amount in the wallet |
| - - amount_awaiting_confirmation | number | Amount awaiting confirmation |
| - - amount_immature | number | Coinbases waiting for lock height |
| - - amount_currently_spendable | number | Amount currently spendable |
| - - amount_locked | number | Amount locked via previous transactions |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/retrieve_summary_info",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Node Height
Retrieve current height from node.
* **URL**
/v1/wallet/owner/node_height
* **Method:**
`GET`
* **URL Params**
None
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:-------|:---------|:-------------------------------------------|
| | number | Node height |
| | bool | Wether the update from node was successful |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/node_height",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### GET Retrieve Txs
Attempt to update outputs and retrieve transactions.
Return whether the outputs were validated against a node and an array of TxLogEntry.
* **URL**
2018-11-12 21:18:54 +03:00
* /v1/wallet/owner/retrieve_txs
* /v1/wallet/owner/retrieve_txs?refresh& id=x
* /v1/wallet/owner/retrieve_txs?tx_id=x
2018-10-04 21:55:03 +03:00
* **Method:**
`GET`
* **URL Params**
**Optional:**
2018-11-12 21:18:54 +03:00
* `refresh` to refresh from node
* `id=[number]` to retrieve only the specified output by id
* `tx_id=[string]` to retrieve only the specified output by tx id
2018-10-04 21:55:03 +03:00
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** Array of
| Field | Type | Description |
|:----------------------|:---------|:----------------------------------------------------------------------------|
| | bool | Whether it was refreshed from node |
| - | []object | Array of transactions |
| - - | object | TxLogEntry |
| - - - id | number | Local id for this transaction (distinct from a slate transaction id) |
| - - - tx_slate_id | string | Slate transaction this entry is associated with, if any |
| - - - tx_type | string | Transaction type |
| - - - creation_ts | string | Time this tx entry was created |
| - - - confirmation_ts | string | Time this tx was confirmed (by this wallet) |
| - - - confirmed | bool | Whether the inputs+outputs involved in this transaction have been confirmed |
| - - - num_inputs | number | number of inputs involved in TX |
| - - - num_outputs | number | number of outputs involved in TX |
| - - - amount_credited | number | Amount credited via this transaction |
| - - - amount_debited | number | Amount debited via this transaction |
| - - - fee | number | Fee |
| - - - tx_hex | string | The transaction json itself, stored for reference or resending |
*Note on transaction type* : transaction type can be either `ConfirmedCoinbase` , `TxReceived` , `TxSent` , `TxReceivedCancelled` and `TxSentCancelled` .
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/foreign/retrieve_txs",
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
2019-01-10 17:09:56 +03:00
### GET Retrieve Stored Tx
2018-10-04 21:55:03 +03:00
Retrieves a given transaction.
* **URL**
2019-01-10 17:09:56 +03:00
/v1/wallet/owner/retrieve_stored_tx?id=x
2018-10-04 21:55:03 +03:00
* **Method:**
`GET`
* **URL Params**
**Required:**
`id=[number]`
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Content:** A deserialized transaction.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
2019-01-10 17:09:56 +03:00
url: "/v1/wallet/owner/retrieve_stored_tx?id=13",
2018-10-04 21:55:03 +03:00
dataType: "json",
type : "GET",
success : function(r) {
console.log(r);
}
});
```
### POST Issue Send Tx
Send a transaction either directly by http or file (then display the slate)
* **URL**
/v1/wallet/owner/issue_send_tx
* **Method:**
`POST`
* **URL Params**
None
* **Data Params**
**Required:**
| Field | Type | Description |
|:------------------------------|:---------|:-------------------------------------|
| amount | number | Amount to send |
| minimum_confirmations | number | Minimum confirmations |
| method | string | Payment method |
| dest | string | Destination url |
| max_outputs | number | Max number of outputs |
| num_change_outputs | number | Number of change outputs to generate |
| selection_strategy_is_use_all | bool | Whether to use all outputs (combine) |
* **Success Response:**
* **Code:** 200
* **Content:** A new transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/issue_send_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
},
data: {
file: tx_args.json
},
});
```
### POST Finalize Tx
Sender finalization of the transaction. Takes the slate returned by the sender as well as the private file generate on the first send step.
2018-11-28 19:52:55 +03:00
Builds the complete transaction but will **not** sends it to a grin node for propagation. Use [POST Post Tx ](#post-post-tx ) for that.
2018-10-04 21:55:03 +03:00
* **URL**
/v1/wallet/owner/finalize_tx
* **Method:**
`POST`
* **URL Params**
None
* **Data Params**
**Required:** A transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Success Response:**
* **Code:** 200
* **Content:** A new transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/finalize_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
},
data: {
file: tx.json
},
});
```
### POST Cancel Tx
Roll back a transaction and all associated outputs with a given transaction id This means delete all change outputs, (or recipient output if you're recipient), and unlock all locked outputs associated with the transaction used when a transaction is created but never posted.
* **URL**
2018-11-13 13:56:48 +03:00
* /v1/wallet/owner/cancel_tx?id=x
* /v1/wallet/owner/cancel_tx?tx_id=x
2018-10-04 21:55:03 +03:00
* **Method:**
`POST`
* **URL Params**
**Required:**
2018-11-13 13:56:48 +03:00
* `id=[number]` the transaction id
* `tx_id=[string]` the transaction slate id
2018-10-04 21:55:03 +03:00
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/cancel_tx?id=3",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
}
});
```
2018-10-21 23:26:35 +03:00
### POST Post Tx
Push new transaction to the connected node transaction pool. Add `?fluff` at the end of the URL to bypass Dandelion relay.
* **URL**
2018-11-28 19:52:55 +03:00
* /v1/wallet/owner/post_tx
* /v1/wallet/owner/post_tx?fluff
2018-10-21 23:26:35 +03:00
* **Method:**
`POST`
* **URL Params**
2018-11-28 19:52:55 +03:00
**Optional:**
`fluff` to bypass Dandelion relay
2018-10-21 23:26:35 +03:00
* **Data Params**
**Required:** A transaction slate in JSON.
| Field | Type | Description |
|:----------------------|:---------|:--------------------------------------------------------------------------|
| num_participants | number | The number of participants intended to take part in this transaction |
| id | number | Unique transaction ID, selected by sender |
| tx | object | The core transaction data (inputs, outputs, kernels and kernel offset) |
| - offset | []number | The kernel "offset" k2, excess is k1G after splitting the key k = k1 + k2 |
| - body | object | The transaction body - inputs/outputs/kernels |
| - - inputs | []object | List of inputs spent by the transaction |
| - - - features | object | The features of the output being spent |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The commit referencing the output being spent |
| - - outputs | []object | List of outputs the transaction produces |
| - - - features | object | Options for an output's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - commit | []number | The homomorphic commitment representing the output amount |
| - - - proof | []number | A proof that the commitment is in the right range |
| - - kernels | []object | List of kernels that make up this transaction (usually a single kernel) |
| - - - features | object | Options for a kernel's structure or use |
| - - - - bits | number | Representation of the features in bits |
| - - - fee | number | Fee originally included in the transaction this proof is for |
| - - - lock_height | number | The max lock_height of all inputs to this transaction |
| - - - excess | []number | Remainder of the sum of all transaction commitments |
| - - - excess_sig | []number | The signature proving the excess is a valid public key (signs the tx fee) |
| amount | number | Base amount (excluding fee) |
| fee | number | Fee amount |
| height | number | Block height for the transaction |
| lock_height | number | Lock height |
| participant_data | object | Participant data |
| - id | number | Id of participant in the transaction. (For now, 0=sender, 1=rec) |
| - public_blind_excess | []number | Public key corresponding to private blinding factor |
| - public_nonce | []number | Public key corresponding to private nonce |
| - part_sig | []number | Public partial signature |
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/post_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
},
data: {
file: tx.json
},
});
```
2019-02-12 16:39:43 +03:00
### POST Repost Tx
Repost a `sending` transaction to the connected node transaction pool with a given transaction id. Add `?fluff` at the end of the URL to bypass Dandelion relay . This could be used for retry posting when a `sending` transaction is created but somehow failed on posting.
* **URL**
* /v1/wallet/owner/repost?id=x
* /v1/wallet/owner/repost?tx_id=x
* /v1/wallet/owner/repost?fluff& tx_id=x
* **Method:**
`POST`
* **URL Params**
**Required:**
* `id=[number]` the transaction id
* `tx_id=[string]` the transaction slate id
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/repost?id=3",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
}
});
```
2018-10-21 23:26:35 +03:00
2018-10-04 21:55:03 +03:00
### POST Issue Burn Tx
Issue a burn TX.
* **URL**
/v1/wallet/owner/issue_burn_tx
* **Method:**
`POST`
* **URL Params**
None
* **Data Params**
None
* **Success Response:**
* **Code:** 200
* **Error Response:**
* **Code:** 400
* **Sample Call:**
```javascript
$.ajax({
url: "/v1/wallet/owner/issue_burn_tx",
dataType: "json",
type : "POST",
success : function(r) {
console.log(r);
}
});
```
2019-01-07 13:00:52 +03:00
### Add Foreign API Endpoints
For some environments it may be convenient to have the [wallet foreign API ](wallet_foreign_api.md ) available on the same port as the owner API. You can do so by setting the `owner_api_include_foreign` configuration setting to `true` .
