gitlab.com/SiaPrime/SiaPrime@v1.4.1/doc/Exchanges.md

Wallet Information for Exchanges
=======

SiaPrime's wallet differs a bit from Bitcoin's. This guide is to point any exchanges to relevant functions and features of the wallet that may be of unique interest to them.

### Address Management

The SiaPrime wallet follows the concept of an address gap limit [as specified in BIP 44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#Address_gap_limit). The default gap limit is 50. This means the wallet will not allow creation of more than 50 consecutive addresses if none of those 50 addresses have been used on the blockchain.

New addresses can be created via a GET request to the `/wallet/address` endpoint.

### Useful API Endpoints

Below is a list of several endpoints an exchange may find useful. For an overview of all API routes, see [API.md](/doc/API.md).

#### /wallet/watch [POST]

###### Parameters
The parameters should be encoded as JSON.

```
// Array of addresses to be watched
addresses

// Boolean indicating whether we want to remove these 
// address from our watch-list instead of add them
remove

// Boolean indicating whether or not these addresses 
// have been used on the blockchain before. If unused 
// is false, the wallet will rescan the blockchain after 
// this request.
unused

```

###### Response

standard success or error response.

#### /wallet/transactions [GET]

returns a list of transactions related to the wallet.

###### Query String Parameters
```
// Number of most recent transactions to return. 
// Must provide a valid value, defaults to 10 if unspecified.
count // block height

// An optional parameter specifying if we want to filter 
// only transactions being sent or being received by the wallet.
// Can be either "send" or "receive".
category // block height

// A boolean parameter specifying if we want to filter
// only transactions pertaining to addresses being watched via
// the /wallet/watch [POST] command.
watchonly
```

###### JSON Response
```javascript
{
  // The most recent 'count' transactions satisfying the filter criteria.
  "confirmedtransactions": [
    {
      // See the documentation for '/wallet/transaction/:id' for more information.
    }
  ],

  // All of the unconfirmed transactions.
  "unconfirmedtransactions": [
    {
      // See the documentation for '/wallet/transaction/:id' for more information.
    }
  ]
}
```

#### /wallet/address [GET]

creates a new address from the wallet generated by the primary seed. An error will
be returned if the wallet is locked.

###### JSON Response
```javascript
{
  // Wallet address that can receive SCP. Addresses are 76 character long hex strings.
  "address": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab"
}
```

#### /wallet/siacoins [POST]

Function: Send SCP to an address or set of addresses. The outputs are
arbitrarily selected from addresses in the wallet. If 'outputs' is supplied,
'amount' and 'destination' must be empty. The number of outputs should not
exceed 400; this may result in a transaction too large to fit in the
transaction pool.

###### Query String Parameters
```
// Number of hastings being sent. A hasting is the smallest unit in SiaPrime. There
// are 10^24 hastings in a single unit of SCP.
amount      // hastings

// Address that is receiving the coins.
destination // address

// JSON array of outputs. The structure of each output is:
// {"unlockhash": "<destination>", "value": "<amount>"}
outputs
```

###### JSON Response
```javascript
{
  // Array of IDs of the transactions that were created when sending the coins.
  // The last transaction contains the output headed to the 'destination'.
  // Transaction IDs are 64 character long hex strings.
  transactionids [
    "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  ]
}
```

### Examples

#### Send to single address

###### Example POST Request
Use _amount_ and _destination_ parameters.
```
/wallet/siacoins?amount=1000000000000000000000000&destination=1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab
```

###### Expected Response Code
```
200 OK
```

###### Example Response Body
```json
{
  "transactionids": [
    "3918e4a4b4cee46b3e5b28b8a1cc41c064a6f6002d162d396f296c201e6edc13",
    "18b85b7d20f8a87bdadacf11e135ad44db1d93efd0613d23116e8cf255502762"
  ]
}
```


#### Send to set of addresses
Use _outputs_ parameter in the form of a JSON array. _amount_ and _destination_ parameters must be empty.


###### Example POST Request
```
/wallet/siacoins?outputs=[{"unlockhash":"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab","value":"1000000000000000000000000"},{"unlockhash":"abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab1234567890","value":"8000000000000000000000000"},{"unlockhash":"cdef0123456789abcdef0123456789abcdef0123456789ab1234567890abcdef0123456789ab","value":"5000000000000000000000000"}]
```

###### (sample JSON request body for reference)
```json
{
  "outputs": [
    {
      "unlockhash":
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
      "value": "1000000000000000000000000"
    },
    {
      "unlockhash":
"abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab1234567890",
      "value": "8000000000000000000000000"
    },
    {
      "unlockhash":
"cdef0123456789abcdef0123456789abcdef0123456789ab1234567890abcdef0123456789ab",
      "value": "20000000000000000000000000"
    }
  ]
}

```

###### Expected Response Code
```
200 OK
```

###### Example Response Body
```json
{
  "transactionids": [
    "21962e0118f3ca5d6fab0262c65bca0220fbcc828c499974d86e7cc4047a0ce5",
    "f2471d550823f2c0616565d8476a7fea5f2b9a841612bf109923c3a54e760721"
  ]
}
```