Skip to content

Latest commit

 

History

History
672 lines (557 loc) · 19.9 KB

rpc.md

File metadata and controls

672 lines (557 loc) · 19.9 KB
Raw

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:

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:

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
{
  "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:

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
{
  "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:

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
{
  "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:

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
{
  "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:

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"
  }
}'
{"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:

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
{
  "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
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}}'
{"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:

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:

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:

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"}}'
{"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:

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
{
  "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:

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
{
  "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:

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
{
  "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:

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
{
  "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:

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
{
  "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:

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 .
{
  "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:

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}