github/atomic-swap
1
1
Fork 0
mirror of https://github.com/AthanorLabs/atomic-swap.git synced 2026-01-08 21:58:07 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
9e3ef7b5271e36230c67f1e6899a1ab17a30fd6d
atomic-swap/docs/rpc.md
Dmitry Holodov 0ab11176c4 unified RPC/websockets client (#472)
2023-05-20 16:29:42 -05:00

19 KiB
Raw Blame History

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_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}
Reference in New Issue View Git Blame Copy Permalink