# 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_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}
```