# JSON-RPC API

The `swapd` program automatically starts a JSON-RPC server that can be used to interact
with the swap network and make/take swap offers.

## `net` namespace

### `net_addresses`

Get the local libp2p listening addresses of the node. Unless you have a public IP
directly attached to your host, these are not the addresses that remote hosts will
directly connect to.


Parameters:
- none

Returns:
- `addresses`: list of libp2p multiaddresses the swap daemon is currently listening on.

Example:

```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"net_addresses","params":{}}' \
| jq .
```
```
{
  "jsonrpc": "2.0",
  "result": {
    "addresses": [
      "/ip4/172.31.32.254/tcp/9900/p2p/12D3KooWQQWDJ7KA1Fwdf2ejWz9VXHKvY8cC5PB7Sf34fbEGbsgV",
      "/ip4/127.0.0.1/tcp/9900/p2p/12D3KooWQQWDJ7KA1Fwdf2ejWz9VXHKvY8cC5PB7Sf34fbEGbsgV",
      "/ip4/172.31.32.254/udp/9900/quic-v1/p2p/12D3KooWQQWDJ7KA1Fwdf2ejWz9VXHKvY8cC5PB7Sf34fbEGbsgV",
      "/ip4/127.0.0.1/udp/9900/quic-v1/p2p/12D3KooWQQWDJ7KA1Fwdf2ejWz9VXHKvY8cC5PB7Sf34fbEGbsgV"
    ]
  },
  "id": "0"
}
```

### `net_discover`

Discover peers on the network via DHT that have active swap offers.

Parameters:
- `provides`: (optional) one of `ETH` or `XMR`, depending on which offer you are searching
  for. **Note**: Currently only `XMR` offers are supported. Default is `XMR`.
- `searchTime`: (optional) time in seconds to perform the search. Default is 12s.

Returns:
- `peers`: list of lists of peers's multiaddresses. A peer may have multiple multiaddresses, so the nested list pertains to a single peer.

Example:

```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"net_discover","params":{"searchTime":3}}' \
| jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "peerIDs": [
      [
        "12D3KooWHLUrLnJtUbaGzTSi6azZavKhNgUZTtSiUZ9Uy12v1eZ7",
        "12D3KooWGBw6ScWiL6k3pKNT2LR9o6MVh5CtYj1X8E1rdKueYLjv"
      ]
    ]
  },
  "id": "0"
}
```

### `net_queryAll`

Discover peers on the network via DHT that have active swap offers and gets all their swap offers.

Parameters:
- `provides`: (optional) one of `ETH` or `XMR`, depending on which offer you are searching
  for. **Note**: Currently only `XMR` offers are supported. Default is `XMR`.
- `searchTime`: (optional) duration in seconds for which to perform the search. Default is 12s.

Returns:
- `peersWithOffers`: list of peers's multiaddresses and their current offers.

Example:

```bash
curl -s -X POST http://127.0.0.1:5001 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"net_queryAll","params":{"searchTime":3}}' \
| jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "peersWithOffers": [
      {
        "peerID": "12D3KooWGVzz2d2LSceVFFdqTYqmQXTqc5eWziw7PLRahCWGJhKB",
        "offers": [
          {
            "offerID": "0xa7429fdb7ce0c0b19bd2450cb6f8274aa9d86b3e5f9386279e95671c24fd8381",
            "provides": "XMR",
            "minAmount": "0.1",
            "maxAmount": "1",
            "exchangeRate": "0.5",
            "ethAsset": "ETH"
          }
        ]
      },
      {
        "peerID": "12D3KooWS8iKxqsGTiL3Yc1VaAfg99U5km1AE7bWYQiuavXj3Yz6",
        "offers": [
          {
            "offerID": "0x25188edd7573f43fca5760f0aacdc1a358171a8fc6bdf11876fa937f77fc583c",
            "minAmount": "0.1",
            "maxAmount": "1",
            "provides": "XMR",
            "exchangeRate": "0.49",
            "ethAsset": "ETH"
          }
        ]
      }
    ]
  },
  "id": "0"
}
```

### `net_queryPeer`

Query a specific peer for their current active offers.

Parameters:
- `multiaddr`: multiaddress of the peer to query. Found via `net_discover`.

Returns:
- `offers`: list of the peer's current active offers.

Example:

```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"net_queryPeer","params":
{"peerID":"12D3KooWGBw6ScWiL6k3pKNT2LR9o6MVh5CtYj1X8E1rdKueYLjv"}}' \
| jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "offers": [
      {
        "version": "0.1.0",
        "offerID": "0xa7429fdb7ce0c0b19bd2450cb6f8274aa9d86b3e5f9386279e95671c24fd8381",
        "provides": "XMR",
        "minAmount": "0.5",
        "maxAmount": "1",
        "exchangeRate": "0.1",
        "ethAsset": "ETH"
      }
    ]
  },
  "id": "0"
}
```

### `net_makeOffer`

Make a new swap offer and advertise it on the network. **Note:** Currently only XMR offers can be made.

Parameters:
- `minAmount`: minimum amount to swap, in XMR.
- `maxAmount`: maximum amount to swap, in XMR.
- `exchangeRate`: exchange rate of ETH-XMR for the swap, expressed in a fraction of
  XMR/ETH. For example, if you wish to trade 10 XMR for 1 ETH, the exchange rate would be
  0.1.
- `ethAsset`: (optional) Ethereum asset to trade, either an ERC-20 token address or the
  zero address for regular ETH. default: regular ETH
- `relayerEndpoint`: (optional) RPC endpoint of the relayer to use for submitting claim
  transactions.
- `relayerFee`: (optional) Fee in ETH that the relayer receives for
  submitting the claim transaction. If `relayerEndpoint` is set and this is not set, it defaults to 0.01 ETH.

Returns:
- `offerID`: ID of the swap offer.

Example:
```bash
curl -s -X POST http://127.0.0.1:5001 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"net_makeOffer",
"params":{"minAmount":"1", "maxAmount":"10", "exchangeRate": "0.1"}}' \
| jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "peerID": "12D3KooWGBw6ScWiL6k3pKNT2LR9o6MVh5CtYj1X8E1rdKueYLjv",
    "offerID": "0x9549685d15cd9a136111db755e5440b4c95e266ba39dc0c84834714d185dc6f0"
  },
  "id": "0"
}
```

### `net_takeOffer`

Take an advertised swap offer. This call will initiate and execute an atomic swap.
**Note:** You must be the ETH holder to take a swap.

Parameters:
- `peerID`: ID of the peer to swap with.
- `offerID`: ID of the swap offer.
- `providesAmount`: amount of ETH you will be providing. Must be between the offer's
  `minAmount * exchangeRate` and `maxAmount * exchangeRate`. For example, if the offer has
  a minimum of 1 XMR and a maximum of 5 XMR and an exchange rate of 0.1, you must provide
  between 0.1 ETH and 0.5 ETH.

Returns:
- null

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"net_takeOffer",
  "params":{
    "peerID":"12D3KooWGBw6ScWiL6k3pKNT2LR9o6MVh5CtYj1X8E1rdKueYLjv",
    "offerID":"0x9549685d15cd9a136111db755e5440b4c95e266ba39dc0c84834714d185dc6f0",
    "providesAmount": "0.3"
  }
}'
```
```json
{"jsonrpc":"2.0","result":null,"id":"0"}
```

## `personal` namespace

### `personal_balances`

Returns combined information of both the Monero and Ethereum account addresses  and balances.

Parameters:
- none

Returns:
- `moneroAddress`: primary monero address of the swapd wallet
- `piconeroBalance`: balance the swapd wallet in piconero
- `piconeroUnlockedBalance`: balance the swapd wallet in piconero that is spendable immediately
- `blocksToUnlock`: number of blocks until the full piconero_balance will be unlocked
- `ethAddress`: address of the swapd ethereum wallet
- `weiBalance`: balance of the ethereum wallet in wei

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"personal_balances","params":{}}' | jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "moneroAddress": "5BVXdWxKp5aMWRfkAiWYb38dPuDFDwTYwCL5ymSoe9CPcLN3c8BanUsiBG8KaGtmQ8W6X2yzCCsvsGjuSYvn8LSZUUV7QB3",
    "piconeroBalance": 149935630269820,
    "piconeroUnlockedBalance": 138815986625976,
    "blocksToUnlock": 37,
    "ethAddress": "0x297d1DdeA7224252fD629442989C569f23Ffc7FD",
    "weiBalance": 429169302264321300
  },
  "id": "0"
}
```

### `personal_setSwapTimeout`

Configures the `_timeoutDuration` used when the ethereum newSwap transaction is created.
This method is only for testing. In non-dev networks, the swaps are configured to fail if
you don't use the defaults.

Parameters:
- `timeout`: duration value in seconds 

Returns:
- null

```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"personal_setSwapTimeout","params":{"timeout":7200}}'
```
```json
{"jsonrpc":"2.0","result":null,"id":"0"}
```

### `personal_setSwapTimeout`

Sets the duration between swap initiation and t1 and t1 and t2, in seconds.

Parameters:
- `duration`: duration of timeout, in seconds

Returns:
- null

Example:
```bash
curl -X POST http://127.0.0.1:5002 -d '{"jsonrpc":"2.0","id":"0","method":"personal_setSwapTimeout","params":{"duration": 120}}' -H 'Content-Type: application/json'
#{"jsonrpc":"2.0","result":null,"id":"0"}
```

### `personal_getSwapTimeout`

Returns the duration between swap initiation and t1 and t1 and t2, in seconds

Parameters:
- none

Returns:
- `timeout`: timeout in seconds

Example:
```bash
curl -X POST http://127.0.0.1:5002 -d '{"jsonrpc":"2.0","id":"0","method":"personal_getSwapTimeout","params":{}}' -H 'Content-Type: application/json'
#{"jsonrpc":"2.0","result":{"timeout":120},"id":"0"}
```

## `swap` namespace

### `swap_cancel`

Attempts to cancel an ongoing swap. Note that depending on the swap's stage, it may not be possible to cancel the swap and receive a refund.

Parameters:
- `id`: id of the swap to cancel.

Returns:
- `status`: exit status of the swap.

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_cancel",
"params":{"offerID": "0x17c01ad48a1f75c1456932b12cb51d430953bb14ffe097195b1f8cace7776e70"}}'
```
```json
{"jsonrpc":"2.0","result":{"status":"Success"},"id":"0"}
```

### `swap_getOngoing`

Gets information for ongoing swaps. If no ID is provided, all ongoing swaps are returned. Otherwise, only the swap with the specified ID is returned.

Parameters:
- `offerID`: (optional) the swap's ID.

Returns:
- `swaps`: a list of ongoing swaps. If an offerID is provided, this returns only the swap with that ID, if it exists.

Each items in `swaps` contains:
- `id`: the swap ID.
- `provided`: the coin provided during the swap.
- `providedAmount`: the amount of coin provided during the swap.
- `receivedAmount`: the amount of coin expected to be received during the swap.
- `exchangeRate`: the exchange rate of the swap, expressed in a ratio of XMR/ETH.
- `status`: the swap's status.
- `startTime`: the start time of the swap (in RFC 3339 format).
- `timeout1`: the time at which the ETH-taker can always claim ETH, and the ETH-maker can no longer refund.
- `timeout2`: the time at which the ETH-taker can no longer claim ETH, and the ETH-maker is able to refund.

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_getOngoing",
"params":{"offerID":"0xa7429fdb7ce0c0b19bd2450cb6f8274aa9d86b3e5f9386279e95671c24fd8381"}}' | jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "swaps": [
      {
        "id": "0xb12d3ecf4d437cfe682e6d455e4a9b2432e730e51029f2551e923b9695f36063",
        "provided": "ETH",
        "providedAmount": "0.006",
        "expectedAmount": "0.12",
        "exchangeRate": "0.05",
        "status": "ETHLocked",
        "startTime": "2023-03-18T16:47:50.598029743-04:00",
        "timeout1": "2023-03-18T16:49:55-04:00",
        "timeout2": "2023-03-18T16:51:55-04:00"
      }
    ]
  },
  "id": "0"
}
```

To get all ongoing swaps:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_getOngoing","params":{}}' | jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "swaps": [
      {
        "id": "0x4e3c5db727b312ff7eefa6d6e18ac44285e20b75e5255c16255a9b741bc311d3",
        "provided": "ETH",
        "providedAmount": "0.1",
        "expectedAmount": "0.1",
        "exchangeRate": "1",
        "status": "ETHLocked",
        "startTime": "2023-03-18T16:52:56.304958446-04:00",
        "timeout1": "2023-03-18T16:55:01-04:00",
        "timeout2": "2023-03-18T16:57:01-04:00"
      },
      {
        "id": "0x8f23b7e187b1db26fcfd23c1699c3e56221153fd7225ada0b0cae8fdbd1cab65",
        "provided": "ETH",
        "providedAmount": "0.1",
        "expectedAmount": "0.1",
        "exchangeRate": "1",
        "status": "ETHLocked",
        "startTime": "2023-03-18T16:53:02.642556563-04:00",
        "timeout1": "2023-03-18T16:55:07-04:00",
        "timeout2": "2023-03-18T16:57:07-04:00"
      }
    ]
  },
  "id": "0"
}
```

### `swap_getPast`

Gets information for past swaps. If no ID is provided, all past swaps are returned. Otherwise, only the swap with the specified ID is returned.

Parameters:
- `offerID`: (optional) the swap's ID.

Returns:
- `swaps`: a list of past swaps. If an offerID is provided, this returns only the swap with that ID, if it exists.

Each items in `swaps` contains:
- `id`: the swap ID.
- `provided`: the coin provided during the swap.
- `providedAmount`: the amount of coin provided during the swap.
- `receivedAmount`: the amount of coin expected to be received during the swap.
- `exchangeRate`: the exchange rate of the swap, expressed in a ratio of XMR/ETH.
- `status`: the swap's exit status.
- `startTime`: the start time of the swap (in RFC 3339 format).
- `end`: the end time of the swap (in RFC 3339 format).

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_getPast",
"params":{"offerID": "0xb12d3ecf4d437cfe682e6d455e4a9b2432e730e51029f2551e923b9695f36063"}}' \
| jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "swaps": [
      {
        "id": "0xb12d3ecf4d437cfe682e6d455e4a9b2432e730e51029f2551e923b9695f36063",
        "provided": "ETH",
        "providedAmount": "0.006",
        "expectedAmount": "0.12",
        "exchangeRate": "0.05",
        "status": "Success",
        "startTime": "2023-03-18T16:47:50.598029743-04:00",
        "endTime": "2023-03-18T16:48:14.942103399-04:00"
      }
    ]
  },
  "id": "0"
}
```

### `swap_getStatus`

Gets the status of an ongoing swap.

Parameters:
- `id`: id of the swap to get the stage of

Returns:
- `stage`: stage of the swap
- `info`: description of the swap's stage
- `startTime`: the start time of the swap (in RFC 3339 format).

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_getStatus",
"params":{"id": "0xbe6cb622906510e69339fa5d8e7d60c90bad762deb8d06985466dd9144809040"}}' \
| jq
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "ETHLocked",
    "info": "the ETH provider has locked their ether, but no XMR has been locked",
    "startTime": "2023-02-20T23:52:28.826764666Z"
  },
  "id": "0"
}
```

### `swap_clearOffers`

Clears one or more offers if offer IDs are passed, or all offers if no offer IDs
are passed. This method is only for removing offers that have not been taken,
use `swap_cancel` to cancel an active swap.

Parameters:
- `id`: id of the swap to get the stage of
- `offerIDs`: (optional) Array of offer IDs to clear, or empty to clear all offers

Returns:
- null

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_clearOffers",
  "params": {
    "offerIds": [
      "0xd66041fd63512c18ff6554c8b4c608be40c8eaa95e29e08af08cf632c7040595"
    ]
  }
}' | jq
```
```json
{
  "jsonrpc": "2.0",
  "result": null,
  "id": "0"
}
```

### `swap_suggestedExchangeRate`

Returns the current mainnet exchange rate expressed as the XMR/ETH price ratio.

Parameters:
- none

Returns:
- `ethUpdatedAt`: time when the ETH price was last updated (in RFC 3339 format).
- `ethPrice`: current ETH/USD price (max 8 decimal points).
- `xmrUpdatedAt`: time when the XMR price was last updated (in RFC 3339 format).
- `xmrPrice`: the current XMR/USD price (max 8 decimal points).
- `exchangeRate`: the exchange rate expressed as the XMR/ETH price ratio.

Example:
```bash
curl -s -X POST http://127.0.0.1:5000 -H 'Content-Type: application/json' -d \
'{"jsonrpc":"2.0","id":"0","method":"swap_suggestedExchangeRate","params":{}}' \
| jq .
```
```json
{
  "jsonrpc": "2.0",
  "result": {
    "ethUpdatedAt": "2023-01-12T14:55:35-06:00",
    "ethPrice": "1430.98158542",
    "xmrUpdatedAt": "2023-01-12T14:22:23-06:00",
    "xmrPrice": "170.9978",
    "exchangeRate": "0.119497"
  },
  "id": "0"
}
```

## websocket subscriptions

The daemon also runs a websockets server that can be used to subscribe to push
notifications for updates. You can use the command-line tool `wscat` to easily connect to
a websockets server.

### `swap_subscribeStatus`

Subscribe to updates of status of a swap. Pushes a notification each time the stage
updates, and a final push when the swap completes, containing its completion status.

Paramters:
- `offerID`: the swap ID.

Returns:
- `status`: the swap's status.

Example:
```bash
wscat -c ws://localhost:5001/ws
# Connected (press CTRL+C to quit)

# > {"jsonrpc":"2.0", "method":"swap_subscribeStatus", "params": {"offerID": "0x6610ef5ba1c093a5c88eb0c2b21be22aa92e68943ac88da1cd45b3e58f8f3166"}, "id": 0}

# < {"jsonrpc":"2.0","result":{"status":"XMRLocked"},"error":null,"id":null}
# < {"jsonrpc":"2.0","result":{"status":"Success"},"error":null,"id":null}
```

### `net_makeOfferAndSubscribe`

Make a swap offer and subscribe to updates on it. A notification will be pushed with the
swap ID when the offer is taken, as well as status updates after that, until the swap has
completed.

Parameters:
- `minAmount`: minimum amount to swap, in XMR.
- `maxAmount`: maximum amount to swap, in XMR.
- `exchangeRate`: exchange rate of ETH-XMR for the swap, expressed in a fraction of
  XMR/ETH. For example, if you wish to trade 10 XMR for 1 ETH, the exchange rate would be
  0.1.
- `ethAsset`: (optional) Ethereum asset to trade, either an ERC-20 token address or the
  zero address for regular ETH. default: regular ETH

Returns:
- `offerID`: ID of the offer which will become the ID of the swap when taken.
- `peerID`: Your peer ID which needs to be specified by the party taking the offer.
- `status`: the swap's status.

Example (including notifications when swap is taken):
```
wscat -c ws://localhost:5000/ws
Connected (press CTRL+C to quit)

> {"jsonrpc":"2.0", "method":"net_makeOfferAndSubscribe", "params": {"minAmount": "0.1", "maxAmount": "1", "exchangeRate": "0.05"}, "id": 0}

< {"jsonrpc":"2.0","result":{"peerID":"12D3KooWNseb7Ei8Xx1aBKjSFoZ9PGfdxN9MwQxfSRxsBAyA8op4","offerID":"0x64f49193dc5e8d70893331498b76a156e33ed8cdf46a1f901c7fab59a827e840"},"error":null,"id":null}
< {"jsonrpc":"2.0","result":{"status":"KeysExchanged"},"error":null,"id":null}
< {"jsonrpc":"2.0","result":{"status":"XMRLocked"},"error":null,"id":null}
< {"jsonrpc":"2.0","result":{"status":"Success"},"error":null,"id":null}
```

### `net_takeOfferAndSubscribe`

Take an advertised swap offer and subscribe to updates on it. This call will initiate and
execute an atomic swap.

Parameters:
- `peerID`: Peer ID of the XMR maker, the party that created the offer.
- `offerID`: ID of the swap offer.
- `providesAmount`: amount of ETH you will be providing. Must be between the offer's
  `minAmount * exchangeRate` and `maxAmount * exchangeRate`. For example, if the
  offer has a minimum of 1 XMR and a maximum of 5 XMR and an exchange rate of 0.1, you
  must provide between 0.1 ETH and 0.5 ETH.

Returns:
- `offerID`: ID of the initiated swap.
- `status`: the swap's status.

Example:
```
wscat -c ws://localhost:5001/ws
Connected (press CTRL+C to quit)

> {"jsonrpc":"2.0", "method":"net_takeOfferAndSubscribe", "params": {"peerID": "12D3KooWNseb7Ei8Xx1aBKjSFoZ9PGfdxN9MwQxfSRxsBAyA8op4", "offerID": "0x64f49193dc5e8d70893331498b76a156e33ed8cdf46a1f901c7fab59a827e840", "providesAmount": "0.025"}, "id": 0}

< {"jsonrpc":"2.0","result":{"status":"ExpectingKeys"},"error":null,"id":null}
< {"jsonrpc":"2.0","result":{"status":"ETHLocked"},"error":null,"id":null}
< {"jsonrpc":"2.0","result":{"status":"ContractReady"},"error":null,"id":null}
< {"jsonrpc":"2.0","result":{"status":"Success"},"error":null,"id":null}
```
