Skip to main content
API docs by Redocly

HOPRd Rest API v2 (2.0.0)

Download OpenAPI specification:Download

E-mail: [email protected] License: GPL-3.0

This Rest API enables developers to interact with a hoprd node programatically.

Find out more about HOPR and HOPRd.

Account

accountWithdraw

Withdraw funds from this node to your ethereum wallet address. You can choose whitch currency you want to withdraw, NATIVE or HOPR.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
currency
required
string (Currency)
Enum: "NATIVE" "HOPR"

Supported currencies, NATIVE used for the interacting with blockchain or HOPR used to fund channels.

amount
required
string <amount>

Amount to withdraw in the currency's smallest unit.

recipient
required
string <address> (NativeAddress)

Blockchain-native account address. Can be funded from external wallets (starts with 0x...). It can't be used internally to send / receive messages, open / close payment channels.

Responses

Request samples

Content type
application/json
{
  • "currency": "NATIVE",
  • "amount": "1337",
  • "recipient": 1.339446426793328e+48
}

Response samples

Content type
application/json
{
  • "receipt": "0x37954ca4a630aa28f045df2e8e604cae22071046042e557355acf00f4ef20d2e"
}

accountGetBalances

Get node's HOPR and native balances. HOPR tokens from this balance is used to fund payment channels between this node and other nodes on the network. NATIVE balance is used to pay for the gas fees for the blockchain network.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "native": "1000000000000000000",
  • "hopr": "10000000000000000000"
}

accountGetAddresses

Get node's HOPR and native addresses. HOPR address is also called PeerId and can be used by other node owner to interact with this node.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "nativeAddress": "string",
  • "hoprAddress": "string",
  • "native": 1.339446426793328e+48,
  • "hopr": "16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar"
}

accountGetAddress Deprecated

Get node's HOPR and native addresses. HOPR address is also called PeerId and can be used by other node owner to interact with this node.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "nativeAddress": "string",
  • "hoprAddress": "string",
  • "native": 1.339446426793328e+48,
  • "hopr": "16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar"
}

Aliases

aliasesGetAliases

Get all aliases you set previously and thier corresponding peer IDs.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "alice": "16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar",
  • "bob": "16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar"
}

aliasesSetAlias

Instead of using HOPR address, we can assign HOPR address to a specific name called alias. Give an address a more memorable alias and use it instead of Hopr address. Aliases are kept locally and are not saved or shared on the network.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
peerId
required
string <peerId>

PeerId that we want to set alias to.

alias
required
string

Alias that we want to attach to peerId.

Responses

Request samples

Content type
application/json
{
  • "peerId": "16Uiu2HAmUsJwbECMroQUC29LQZZWsYpYZx1oaM1H9DBoZHLkYn12",
  • "alias": "Alice"
}

Response samples

Content type
application/json
{
  • "status": "INVALID_PEERID"
}

aliasesGetAlias

Get the PeerId (Hopr address) that have this alias assigned to it.

Authorizations:
keySchemepasswordScheme
path Parameters
alias
required
string
Example: Alice

Alias that we previously assigned to some PeerId.

Responses

Response samples

Content type
application/json
{
  • "peerId": "16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar"
}

aliasesRemoveAlias

Unassign an alias from a PeerId. You can always assign back alias to that PeerId using /aliases endpoint.

Authorizations:
keySchemepasswordScheme
path Parameters
alias
required
string
Example: Alice

Alias that we want to remove.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "error": "string"
}

Channels

channelsFundChannels

Fund one or two payment channels between this node and the counter party provided.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
peerId
required
string <peerId>

PeerId to fund the outgoing/incoming channels with.

outgoingAmount
required
string <amount>

Amount of HOPR tokens to fund the outgoing channel (node -> counterparty). It will be used to pay for sending messages through channel

incomingAmount
required
string <amount>

Amount of HOPR tokens to fund the incoming channel (counterparty -> node). It will be used to pay for sending messages through channel

Responses

Request samples

Content type
application/json
{
  • "peerId": "16Uiu2HAmUsJwbECMroQUC29LQZZWsYpYZx1oaM1H9DBoZHLkYn12",
  • "outgoingAmount": "1000000",
  • "incomingAmount": "1000000"
}

Response samples

Content type
application/json
{
  • "receipt": "0x37954ca4a630aa28f045df2e8e604cae22071046042e557355acf00f4ef20d2e"
}

channelsOpenChannel

Opens a payment channel between this node and the counter party provided. This channel can be used to send messages between two nodes using other nodes on the network to relay the messages. Each message will deduce its cost from the funded amount to pay other nodes for relaying your messages. Opening a channel can take a little bit of time, because it requires some block confirmations on the blockchain.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
peerId
required
string <peerId>

PeerId that we want to transact with using this channel.

amount
required
string <amount>

Amount of HOPR tokens to fund the channel. It will be used to pay for sending messages through channel

Responses

Request samples

Content type
application/json
{
  • "peerId": "16Uiu2HAmUsJwbECMroQUC29LQZZWsYpYZx1oaM1H9DBoZHLkYn12",
  • "amount": "1000000"
}

Response samples

Content type
application/json
{
  • "channelId": "0x04e50b7ddce9770f58cebe51f33b472c92d1c40384759f5a0b1025220bf15ec5",
  • "receipt": "0x37954ca4a630aa28f045df2e8e604cae22071046042e557355acf00f4ef20d2e"
}

channelsGetChannels

Lists all active channels between this node and other nodes on the Hopr network. By default response will contain all incomming and outgoing channels that are either open, waiting to be opened, or waiting to be closed. If you also want to receive past channels that were closed, you can pass includingClosed in the request url query.

Authorizations:
keySchemepasswordScheme
query Parameters
includingClosed
string
Example: includingClosed=false

When includingClosed is passed the response will include closed channels which are ommited by default.

Responses

Response samples

Content type
application/json
{
  • "incoming": [
    ],
  • "outgoing": [
    ]
}

channelsRedeemTickets

Redeems your tickets for this channel. Redeeming will change your tickets into Hopr tokens if they are winning ones. You can check how much tickets given channel has by calling /channels/{peerid}/tickets endpoint. Do this before channel is closed as neglected tickets are no longer valid for redeeming.

Authorizations:
keySchemepasswordScheme
path Parameters
peerid
required
string <peerId>
Example: 16Uiu2HAm91QFjPepnwjuZWzK5pb5ZS8z8qxQRfKZJNXjkgGNUAit

PeerId attached to the channel.

Responses

Response samples

Content type
application/json
{
  • "status": "INVALID_PEERID"
}

channelsGetTickets

Get tickets earned by relaying data packets by your node for the particular channel.

Authorizations:
keySchemepasswordScheme
path Parameters
peerid
required
string <peerId>
Example: 16Uiu2HAm91QFjPepnwjuZWzK5pb5ZS8z8qxQRfKZJNXjkgGNUAit

PeerId attached to the channel.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

channelsCloseChannel

Close a opened channel between this node and other node. Once you've initiated channel closure, you have to wait for a specified closure time, it will show you a closure initiation message with cool-off time you need to wait. Then you will need to send the same command again to finalize closure. This is a cool down period to give the other party in the channel sufficient time to redeem their tickets.

Authorizations:
keySchemepasswordScheme
path Parameters
peerid
required
string <peerId>
Example: 16Uiu2HAmUsJwbECMroQUC29LQZZWsYpYZx1oaM1H9DBoZHLkYn12

PeerId attached to the channel that we want to close.

direction
required
string
Enum: "incoming" "outgoing"

Specify which channel should be fetched, incoming or outgoing.

Responses

Response samples

Content type
application/json
{
  • "receipt": "0x37954ca4a630aa28f045df2e8e604cae22071046042e557355acf00f4ef20d2e",
  • "channelStatus": "Closed"
}

channelsGetChannel

Returns information about the channel between this node and provided peerId.

Authorizations:
keySchemepasswordScheme
path Parameters
peerid
required
string <peerId> (HoprAddress)
Example: 16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar

Counterparty peerId assigned to the channel you want to fetch.

direction
required
string
Enum: "incoming" "outgoing"

Specify which channel should be fetched, incoming or outgoing.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Messages

messagesWebsocket

This is a websocket endpoint which streams incoming messages from other nodes. Data is streamed in a stringified Uint8Array instance. Authentication (if enabled) is done via either passing an apiToken parameter in the url or cookie X-Auth-Token. Connect to the endpoint by using a WS client. No preview available. Example: ws://127.0.0.1:3001/api/v2/messages/websocket/?apiToken=myApiToken

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/text
104,101,108,108,111,32,119,111,114,108,100

messagesSign

Signs a message given using the node’s private key. Prefixes messsage with “HOPR Signed Message: ” before signing.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
message
required
string

The message to be signed.

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "signature": 7.115342872866815e+167
}

messagesSendMessage

Send a message to another peer using a given path (list of node addresses that should relay our message through network). If no path is given, HOPR will attempt to find a path.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
body
required
string

The message body which should be sent.

recipient
required
string <peerId>

The recipient HOPR peer id, to which the message is sent.

path
Array of strings <peerId> [ items <peerId > [ 1 .. 3 ] items ]

The path is ordered list of peer ids through which the message should be sent. If no path is provided, a path which covers the nodes minimum required hops will be determined automatically.

hops
integer [ 1 .. 3 ]

Number of required intermediate nodes. This parameter is ignored if path is set.

Responses

Request samples

Content type
application/json
{
  • "body": "Hello",
  • "recipient": "16Uiu2HAm2SF8EdwwUaaSoYTiZSddnG4hLVF7dizh32QFTNWMic2b",
  • "path": [
    ],
  • "hops": 3
}

Response samples

Content type
application/json
"e61bbdda74873540c7244fe69c39f54e5270bd46709c1dcb74c8e3afce7b9e616d"

messageSign Deprecated

Signs a message given using the node’s private key. Prefixes messsage with “HOPR Signed Message: ” before signing.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
message
required
string

The message to be signed.

Responses

Request samples

Content type
application/json
{
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "signature": 7.115342872866815e+167
}

Node

nodeGetVersion

Get release version of the running node.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
"1.83.5"

nodeStreamWebsocket Deprecated

This is a websocket endpoint which streams legacy hopr-admin data. Authentication (if enabled) is done via either passing an apiToken parameter in the url or cookie X-Auth-Token. Connect to the endpoint by using a WS client. No preview available. Example: ws://127.0.0.1:3001/api/v2/node/stream/websocket/?apiToken=myApiToken

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "type": "log",
  • "timestamp": 1644587213977,
  • "content": "Opening channel..."
}

nodePing

Pings another node to check its availability.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
peerId
required
string <peerId>

PeerId associated to the other node that we want to ping.

Responses

Request samples

Content type
application/json
{
  • "peerId": "16Uiu2HAmUsJwbECMroQUC29LQZZWsYpYZx1oaM1H9DBoZHLkYn12"
}

Response samples

Content type
application/json
{
  • "latency": 10
}

nodeGetPeers

Lists information for connected peers and announced peers. Connected peers are nodes which are connected to the node while announced peers are nodes which have announced to the network. Optionally, you can pass quality parameter which would filter out peers with lower quality to the one specified.

Authorizations:
keySchemepasswordScheme
query Parameters
quality
number
Example: quality=0.5

When quality is passed, the response will only include peers with higher or equal quality to the one specified.

Responses

Response samples

Content type
application/json
{
  • "connected": [
    ],
  • "announced": [
    ]
}

nodeGetMetrics

Retrieve Prometheus metrics from the running node.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "error": "string"
}

nodeGetInfo

Information about the HOPR Node, including any options it started with. See the schema of the response to get more information on each field.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "environment": "anvil-localhost",
  • "announcedAddress": [
    ],
  • "listeningAddress": [
    ],
  • "network": "anvil",
  • "hoprToken": "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
  • "hoprChannels": "0x2a54194c8fe0e3CdeAa39c49B95495aA3b44Db63",
  • "hoprNetworkRegistryAddress": "0xBEE1F5d64b562715E749771408d06D57EE0892A7",
  • "connectivityStatus": "GREEN",
  • "isEligible": true,
  • "channelClosurePeriod": 1
}

nodeGetEntryNodes

List all known entry nodes and their multiaddrs and their eligibility state

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

PeerInfo

peerInfoGetPeerInfo

Get information about this peer.

Authorizations:
keySchemepasswordScheme
path Parameters
peerid
required
string <peerId> (HoprAddress)
Example: 16Uiu2HAmVfV4GKQhdECMqYmUMGLy84RjTJQxTWDcmUX5847roBar

HOPR account address, also called a PeerId. Used to send / receive messages, open / close payment channels.

Responses

Response samples

Content type
application/json
{
  • "announced": [
    ],
  • "observed": [
    ]
}

Settings

settingsGetSettings

Get all of the node's settings.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "includeRecipient": true,
  • "strategy": "passive"
}

settingsSetSetting

Change this node's setting value. Check Settings schema to learn more about each setting and the type of value it expects.

Authorizations:
keySchemepasswordScheme
path Parameters
setting
required
string <settingKey>
Example: includeRecipient

Name of the setting we want to change.

Request Body schema: application/json
settingValue
required
any

Responses

Request samples

Content type
application/json
{
  • "settingValue": true
}

Response samples

Content type
application/json
{
  • "status": "INVALID_SETTING | INVALID_SETTING_VALUE"
}

Tickets

ticketsGetStatistics

Get statistics regarding all your tickets. Node gets a ticket everytime it relays data packet in channel.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "pending": 0,
  • "unredeemed": 0,
  • "unredeemedValue": "string",
  • "redeemed": 0,
  • "redeemedValue": "string",
  • "losingTickets": 0,
  • "winProportion": 0,
  • "neglected": 0,
  • "rejected": 0,
  • "rejectedValue": "string"
}

ticketsRedeemTickets

Redeems all tickets from all the channels and exchanges them for Hopr tokens. Every ticket have a chance to be winning one, rewarding you with Hopr tokens.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "error": "string"
}

ticketsGetTickets

Get all tickets earned by relaying data packets by your node from every channel.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Tokens

tokensCreate

Create a new authentication token based on the given information. The new token is returned as part of the response body and must be stored by the client. It cannot be read again in cleartext and is lost, if the client loses the token. An authentication has a lifetime. It can be unbound, meaning it will not expire. Or it has a limited lifetime after which it expires. The requested limited lifetime is requested by the client in seconds.

Authorizations:
keySchemepasswordScheme
Request Body schema: application/json
required
Array of objects (TokenCapability) non-empty

Capabilities attached to the created token.

lifetime
integer >= 1

Lifetime of the token in seconds since creation. Defaults to unlimited lifetime.

description
string

Description associated with the token.

Responses

Request samples

Content type
application/json
{
  • "description": "my test token",
  • "lifetime": 360,
  • "capabilities": [ ]
}

Response samples

Content type
application/json
{
  • "token": "MYtoken1223"
}

tokensGetToken

Get the full token information for the token used in authentication.

Authorizations:
keySchemepasswordScheme

Responses

Response samples

Content type
application/json
{
  • "id": "someTOKENid1223",
  • "description": "this is an interesting token",
  • "capabilities": [
    ]
}

tokensDelete

Deletes a token. Can only be done before the lifetime expired. After the lifetime expired the token is automatically deleted.

Authorizations:
keySchemepasswordScheme
path Parameters
id
required
string
Example: someTOKENid1234

ID of the token which shall be deleted.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "error": "string"
}