Version: 0.23.0

Network

Currency networks list#

Returns all registered currency networks with high-level information.

Request#

GET /networks

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks

Response#

AttributeTypeJSON TypeDescription
abbreviationstringstringAbbreviated name of currency network
addressaddressstring - hex-encoded prefixed with "0x"Contract address of currency network
decimalsintnumberDecimals specified in currency network
namestringstringFull name of the currency network
numUsersintnumberTotal number of users in currency network
capacityImbalanceFeeDivisorintnumberThe divisor on value transferred for the mediator fees
defaultInterestRateBigIntegerstringThe default interest rate for every user in the network
interestRateDecimalsintnumberDecimals of the interest rate
customInterestsboolboolWhether custom interest rate can be set by users
preventMediatorInterestsboolboolWhether to prevent mediators from paying interest
isFrozenboolboolWhether the currency network is frozen

Example Response#

[
{
"abbreviation": "HOU",
"address": "0xC0B33D88C704455075a0724AA167a286da778DDE",
"decimals": 2,
"name": "Hours",
"numUsers": 3,
"capacityImbalanceFeeDivisor": 100,
"defaultInterestRate": "100",
"interestRateDecimals": 2,
"customInterests": false,
"preventMediatorInterests": false,
"isFrozen": false
},
{
"abbreviation": "Fugger",
"address": "0x55bdaAf9f941A5BB3EacC8D876eeFf90b90ddac9",
"decimals": 2,
"name": "FUG",
"numUsers": 3,
"capacityImbalanceFeeDivisor": 100,
"defaultInterestRate": "100",
"interestRateDecimals": 2,
"customInterests": false,
"preventMediatorInterests": false,
"isFrozen": false
}
]

Currency Network Details#

Returns detailed information of currency network.

Request#

GET /networks/:networkAddress

URL Parameters#

NameTypeRequiredDescription
networkAddressstring prefixed with "0x"YESAddress of currency network

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE

Response#

AttributeTypeJSON TypeDescription
abbreviationstringstringAbbreviated name of currency network
addressaddressstring - hex-encoded prefixed with "0x"Contract address of currency network
decimalsintnumberDecimals specified in currency network
namestringstringFull name of the currency network
numUsersintnumberTotal number of users in currency network
capacityImbalanceFeeDivisorintnumberThe divisor on value transferred for the mediator fees
defaultInterestRateBigIntegerstringThe default interest rate for every user in the network
interestRateDecimalsintnumberDecimals of the interest rate
customInterestsboolboolWhether custom interest rate can be set by users
preventMediatorInterestsboolboolWhether to prevent mediators from paying interest
isFrozenboolboolWhether the currency network is frozen

Example Response#

{
"abbreviation": "HOU",
"address": "0xC0B33D88C704455075a0724AA167a286da778DDE",
"decimals": 2,
"name": "Hours",
"numUsers": 3,
"capacityImbalanceFeeDivisor": 100,
"defaultInterestRate": "100",
"interestRateDecimals": 2,
"customInterests": false,
"preventMediatorInterests": false,
"isFrozen": false
}

Users List in Currency Network#

Returns a list of user addresses in a currency network.

Request#

GET /networks/:networkAddress/users

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users

Response#

string[] - Array with addresses of users in currency network

Example Response#

[
"0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"0x7Ff66eb1A824FF9D1bB7e234a2d3B7A3b0345320",
"0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b"
]

Trustlines List in Currency Network#

Returns a list of all trustlines in a currency network.

Request#

GET /networks/:networkAddress/trustlines

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/trustlines

Response#

A list of trustlines with the following attributes:

AttributeTypeDescription
counterPartystringAddress of trustline counterparty
currencyNetworkstringAddress of currency network
userstringAddress of trustline user
balancestringBalance of trustline from point of view of user
givenstringCreditline given to counterparty
receivedstringCreditline received by counterparty
leftGivenstringgiven - balance
leftReceivedstringreceived + balance
interestRateGivenstringInterest Rate given to counterparty
interestRateReceivedstringInterest Rate received from counterparty
isFrozenboolWhether the trustlines is frozen
idstringIdentifier of trustline

Example Response#

[
{
"id": "0xe4332c0bc15bf97933ce54c93af772bb13fad2c4c44e2516eb62d4f6c041e9ab",
"leftReceived": "19848",
"counterParty": "0xB5A3ad8d5A23e5DDD8b8917F709b01396e4d55e4",
"currencyNetwork": "0xC0B33D88C704455075a0724AA167a286da778DDE",
"balance": "-152",
"given": "10000",
"leftGiven": "10152",
"received": "20000",
"interestRateGiven": "1000",
"interestRateReceived": "2000",
"isFrozen": false,
"user": "0x04f9b217b334507c42Ad3b74BFf024c724aBB166"
}
]

User Details in Currency Network#

Returns detailed information of a user in a currency network.

Request#

GET /networks/:networkAddress/users/:userAddress

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network
userAddressstringYESAddress of user

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce

Response#

AttributeTypeJSON TypeDescription
balanceBigIntegerstringSum over balances of all non-frozen trustlines user has in currency network
frozenBalanceBigIntegerstringSum over balances of all frozen trustlines user has in currency network
givenBigIntegerstringSum of all creditlines given by user in currency network
receivedBigIntegerstringSum of all creditlines received by user in currency network
leftGivenBigIntegerstringgiven - balance
leftReceivedBigIntegerstringreceived + balance

Example Response#

{
"balance": "-1000",
"frozenBalance": "1000",
"given": "2000",
"received": "4000",
"leftGiven": "3000",
"leftReceived": "1000"
}

Trustlines of user in currency network#

Returns a list of trustlines a user has in a currency network.

Request#

GET /networks/:networkAddress/users/:userAddress/trustlines

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network
userAddressstringYESAddress of user

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/trustlines

Response#

AttributeTypeDescription
counterPartystringAddress of trustline counterparty
currencyNetworkstringAddress of currency network
userstringAddress of trustline user
balancestringBalance of trustline from point of view of user
givenstringCreditline given to counterparty
receivedstringCreditline received by counterparty
leftGivenstringgiven - balance
leftReceivedstringreceived + balance
interestRateGivenstringInterest Rate given to counterparty
interestRateReceivedstringInterest Rate received from counterparty
isFrozenboolWhether the trustlines is frozen
idstringIdentifier of trustline

Example Response#

[
{
"id": "0xe4332c0bc15bf97933ce54c93af772bb13fad2c4c44e2516eb62d4f6c041e9ab",
"leftReceived": "19848",
"counterParty": "0xB5A3ad8d5A23e5DDD8b8917F709b01396e4d55e4",
"currencyNetwork": "0xC0B33D88C704455075a0724AA167a286da778DDE",
"balance": "-152",
"given": "10000",
"leftGiven": "10152",
"received": "20000",
"interestRateGiven": "1000",
"interestRateReceived": "2000",
"isFrozen": false,
"user": "0x04f9b217b334507c42Ad3b74BFf024c724aBB166"
}
]

Trustline between users in currency network#

Returns a trustline between users A and B in a currency network.

Request#

GET /networks/:networkAddress/users/:userAddressA/trustlines/:userAddressB

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network
userAddressAstringYESAddress of user A
userAddressBstringYESAddress of user B

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/trustlines/0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b

Response#

AttributeTypeDescription
counterPartystringAddress of trustline counterparty
userstringAddress of trustline user
balancestringBalance of trustline from point of view of user (A)
givenstringCreditline given to counterparty
receivedstringCreditline received by counterparty
leftGivenstringgiven - balance
leftReceivedstringreceived + balance
interestRateGivenstringInterest Rate given to counterparty
interestRateReceivedstringInterest Rate received from counterparty
isFrozenboolWhether the trustline is forzen
idstringIdentifier of trustline

Example Response#

{
"id": "0xe4332c0bc15bf97933ce54c93af772bb13fad2c4c44e2516eb62d4f6c041e9ab",
"leftReceived": "19848",
"counterParty": "0xB5A3ad8d5A23e5DDD8b8917F709b01396e4d55e4",
"balance": "-152",
"given": "10000",
"leftGiven": "10152",
"received": "20000",
"interestRateGiven": "1000",
"interestRateReceived": "2000",
"isFrozen": false,
"user": "0x04f9b217b334507c42Ad3b74BFf024c724aBB166"
}

Spendable amount and path to any user in currency network#

Returns an estimation on the amount user A can spend to any reachable user B in a currency network.

Request#

POST /networks/:network_address/max-capacity-path-info

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network

Data Parameters#

NameTypeRequiredDescription
fromstringYESAddress of user who sends transfer
tostringYESAddress of user who receives transfer
maxHopsstringNOUpper bound for hops in transfer path

Example Request#

curl --header "Content-Type: application/json" \
--request POST \
--data '{"from":"0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce","to":"0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b"}' \
https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/max-capacity-path-info

Response#

AttributeTypeDescription
capacitystringEstimated capacity of estimated max capacity path
pathstring[]Addresses of users on max capacity path

Example Response#

{
"capacity": "18",
"path": [
"0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"0xc257274276a4e539741ca11b590b9447b26a8051",
"0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b"
]
}

Transfer path in currency network#

Returns the cheapest path and maximal fees for a transfer.

Request#

POST /networks/:networkAddress/path-info

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network

Data Parameters#

NameTypeRequiredDescription
fromstringYESAddress of user who sends transfer
tostringYESAddress of user who receives transfer
valuestringYESTransfer amount in smallest unit
maxFeesstringNOUpper bound for transfer fees
maxHopsstringNOUpper bound for hops in transfer path
feePayerstringNOEither sender or receiver

Example Request#

curl --header "Content-Type: application/json" \
--request POST \
--data '{"from":"0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce","to":"0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b", "value": "1000"}' \
https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/path-info

Response#

AttributeTypeDescription
pathstring[]Addresses of users on transfer path
valueintTransfer amount in smallest unit
feePayerstringEither sender or receiver
feesstringMaximal transfer fees

Example Response#

{
"path": [
"0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b"
],
"value": 1000,
"fees": "2",
"feePayer": "sender"
}

Closing trustline path in currency network#

This endpoint is used in preparation for closing a trustline. It returns the cheapest path, the fees and a value for a payment, which reduces the balance to zero. At the moment this only works for negative balances.

Request#

POST /networks/:networkAddress/close-trustline-path-info

URL Parameters#

NameTypeRequiredDescription
networkAddressstringYESAddress of currency network

Data Parameters#

NameTypeRequiredDescription
fromstringYESAddress of user who wants to close a trustline
tostringYESAddress of user with whom the trustline should be closed
maxFeesstringNOUpper bound for transfer fees
maxHopsstringNOUpper bound for hops in transfer path

Example Request#

curl --header "Content-Type: application/json" \
--request POST \
--data '{"from":"0x186ec4A5E2c9Ed2B392599843375383D40C94F57","to":"0xaE8446e5ea18F6d7647b28eEf01e568BE672AF6c"}' \
https://relay0.testnet.trustlines.network/api/v1/networks/0xc5F45B680e81759E3FBc4b4a5A94FBd40BAB3fAd/close-trustline-path-info

Response#

AttributeTypeDescription
pathstring[]Addresses of users on transfer path
feesstringEstimated transfer fees
valuestringAmount to be transferred in smallest unit
feePayerstringEither sender or receiver

Example Response#

{
"fees": "6",
"path": [
"0x186ec4A5E2c9Ed2B392599843375383D40C94F57",
"0x37605B30874452551F959811C5F8662329E51EB2",
"0xaE8446e5ea18F6d7647b28eEf01e568BE672AF6c",
"0x186ec4A5E2c9Ed2B392599843375383D40C94F57"
],
"value": "410",
"feePayer": "sender"
}

All events in currency network#

Returns a list of event logs in a currency network.

Request#

GET /networks/:networkAddress/events?type=:type&fromBlock=:fromBlock

URL Parameters#

NameTypeRequiredDescription
networkstringYESAddress of currency network
typestringNOEither TrustlineUpdate, TrustlineUpdateRequest, TrustlineUpdateCancel, Transfer, DebtUpdate, NetworkFreeze, or BalanceUpdate
fromBlockintNOStart of block range

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/events?type=TrustlineUpdate&fromBlock=123456

Response#

Returns a list of the events in a currency network. By default this will return events of type TrustlineUpdate, TrustlineUpdateRequest, TrustlineUpdateCancel, and Transfer See Event Response for a detail of the possible values returned.


Events of a user in currency network#

Returns a list of event logs of a user in a currency network. This means all events where the given user address is either from or to.

Request#

GET /networks/:network/users/:user/events?type=:type&fromBlock=:fromBlock

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/events?type=TrustlineUpdate&fromBlock=123456

URL Parameters#

NameTypeRequiredDescription
networkstringYESAddress of currency network
userstringYESAddress of user
typestringNOEither TrustlineUpdate, TrustlineUpdateRequest, TrustlineUpdateCancel or Transfer
fromBlockintNOStart of block range

Response#

Returns a list of the events of a user in a currency network. These events can be of type TrustlineUpdate, TrustlineUpdateRequest, TrustlineUpdateCancel, Transfer, DebtUpdate, or BalanceUpdate See Event Response for a detail of the possible values returned.


Events of a trustline in currency network#

Returns a list of event logs of a trustline in a currency network from the view of user.

Request#

GET /networks/:network/users/:user/trustlines/:counterParty/events?type=:type&fromBlock=:fromBlock

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/trustlines/0x7Ec3543702FA8F2C7b2bD84C034aAc36C263cA8b/events?type=TrustlineUpdate&fromBlock=123456

URL Parameters#

NameTypeRequiredDescription
networkstringYESAddress of currency network
userstringYESAddress of user, one address of the trustline
counterPartystringYESAddress of counterParty, other address of the trustline
typestringNOEither TrustlineUpdate, TrustlineUpdateRequest, TrustlineUpdateCancel or BalanceUpdate
fromBlockintNOStart of block range

Response#

Returns a list of the events of a trustline, these events can be of type TrustlineUpdate, TrustlineUpdateRequest, TrustlineUpdateCancel, or BalanceUpdate See Event Response for a detail of the possible values returned.


Accrued interests of user#

Returns a list of all accrued interests for user.

Request#

GET /networks/:network/users/:user/interests?startTime=:timestamp&endTime=:timestamp

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/interests?startTime=1579000000&endTime=1579008836

URL Parameters#

NameTypeRequiredDescription
networkstring prefixed with "0x"YESAddress of currency network
userstring prefixed with "0x"YESAddress of concerned user
startTimeintegerNOStart of time window to get list for (default: 0)
endTimeintegerNOEnd of time window to get list for (default: now)

Response#

The response is a list of objects with the following elements:

AttributeTypeJSON TypeDescription
accruedInterestsstringarraylist of accrued interests
useraddressstringAddress of user
counterpartyaddressstringAddress of counterparty

The accuredInterests is a list with the following elements:

AttributeTypeJSON TypeDescription
valueBigIntegerstringsigned interest accrued viewed from user
interestRateintegerintegerinterest rate for this accrued interest
timestampintegerintegertimestamp of accrued interest

Example Response#

[
{
"accruedInterests": [{"value": 123, "interestRate": 1000, "timestamp": 1579000000}, {"value": 456, "interestRate": 2000, "timestamp": 1579001000}],
"user": "0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"counterparty": "0x7Ff66eb1A824FF9D1bB7e234a2d3B7A3b0345320"
},
{
"accruedInterests": [{"value": 123, "interestRate": 1000, "timestamp": 1579000000}, {"value": 456, "interestRate": 2000, "timestamp": 1579001000}],
"user": "0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"counterparty": "0xC0B33D88C704455075a0724AA167a286da778DDE"
}
]

Accrued interests of trustline#

Returns a list of all accrued interests for a trustline in between user and counterparty as seen by user.

Request#

GET /networks/:network/users/:user/interests/:counterparty?startTime=:timestamp&endTime=:timestamp

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/interests/0x7Ff66eb1A824FF9D1bB7e234a2d3B7A3b0345320?startTime=1579000000&endTime=1579008836

URL Parameters#

NameTypeRequiredDescription
networkstring prefixed with "0x"YESAddress of currency network
userstring prefixed with "0x"YESAddress of concerned user
counterpartystring prefixed with "0x"YESAddress of concerned counterparty
startTimeintegerNOStart of time window to get list for (default: 0)
endTimeintegerNOEnd of time window to get list for (default: now)

Response#

The response is a an objects with the following elements:

AttributeTypeJSON TypeDescription
accruedInterestsstringarraylist of accrued interests
useraddressstringAddress of user
counterpartyaddressstringAddress of counterparty

The accuredInterests is a list with the following elements:

AttributeTypeJSON TypeDescription
valueBigIntegerstringsigned interest accrued viewed from user
interestRateintegerintegerinterest rate for this accrued interest
timestampintegerintegertimestamp of accrued interest

Example Response#

{
"accruedInterests": [{"value": 123, "interestRate": 1000, "timestamp": 1579000000}, {"value": 456, "interestRate": 2000, "timestamp": 1579001000}],
"user": "0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"counterparty": "0x7Ff66eb1A824FF9D1bB7e234a2d3B7A3b0345320"
}

Information for transfer in transaction#

Returns information about all trustline transfer applied by transaction with given hash or identified by block hash and log index.

Request#

To get transfer details via transaction hash:

GET /transfers?transactionHash=hash

To get transfer details via transfer id:

GET /transfers?blockHash=hash&logIndex=logindex

Data Parameters#

NameTypeRequiredDescription
transactionHashstringNoHash of transaction responsible for transfer
blockHashstringNoHash of block identifying transfer event
logIndexnumberNoLog index identifying transfer event

Example Request#

To get transfer details via transaction hash:

curl https://relay0.testnet.trustlines.network/api/v1/transfers?transactionHash=0x05c91f6506e78b1ca2413df9985ca7d37d2da5fc076c0b55c5d9eb9fdd7513a6

To get transfer details via transfer id:

curl https://relay0.testnet.trustlines.network/api/v1/transfers?blockHash=0x05c91f6506e78b1ca2413df9985ca7d37d2da5fc076c0b55c5d9eb9fdd7513a6&logIndex=12

Total transferred sum in between users of currency networks#

Returns the total transferred sum from a user to another user in a currency network in a time window.

Request#

GET /networks/:network/users/:sender/transferredSums/:receiver?startTime=:timestamp&endTime=:timestamp

Example Request#

curl https://relay0.testnet.trustlines.network/api/v1/networks/0xC0B33D88C704455075a0724AA167a286da778DDE/users/0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce/transferredSums/0x7Ff66eb1A824FF9D1bB7e234a2d3B7A3b0345320?startTime=1579000000&endTime=1579008836

URL Parameters#

NameTypeRequiredDescription
networkstring prefixed with "0x"YESAddress of currency network
senderstring prefixed with "0x"YESAddress of sender of transfers
receiverstring prefixed with "0x"YESAddress of receiver of transfers
startTimeintegerNOStart of time window to get list for (default: 0)
endTimeintegerNOEnd of time window to get list for (default: now)

Response#

The response is a an objects with the following elements:

AttributeTypeJSON TypeDescription
senderaddressstringAddress of sender of transfers
receiveraddressstringAddress of user
startTimetimestampnumberstart of time window to fetch transfers
endTimetimestampnumberend of time window to fetch transfers
valueBigIntegerstringTotal value sent in between users

Example Response#

{
"sender": "0xcbF1153F6e5AC01D363d432e24112e8aA56c55ce",
"receiver": "0x7Ff66eb1A824FF9D1bB7e234a2d3B7A3b0345320",
"startTime": 1579000000,
"endTime": 1579008836,
"value": "123"
}