API Routes

Jump to:

• DELETE /staking/avalanche/{chain}/validators/{id}

• GET /staking/avalanche/{chain}/validators

• GET /staking/avalanche/{chain}/validators/{id}

• GET /staking/avalanche/billing/report

• GET /staking/avalanche/chains

• POST /staking/avalanche/{chain}/validators

• Error responses

GET /staking/avalanche/chains

Retrieves all the chains that are enabled for the protocol

Parameters

Name	In	Type	Required	Description
Authorization	header	string	yes	The authentication token.

curl -X GET https://api.bloq.com/staking/avalanche/chains \
  -H 'Authorization: Bearer <auth-token>'

Response

Status	Description
200	The list was retrieved.
401	No authentication header found.
403	The authorization token is invalid.

Property	Type	Description
(root)	array	The response.
[]	string	The name of the chain.

Sample response

["fuji", "mainnet"]

GET /staking/avalanche/{chain}/validators

List all of the user's Avalanche validators.

Parameters

Name	In	Type	Required	Description
chain	path	string	yes	The validator's chain: "mainnet" or "fuji".
Authorization	header	string	yes	The authentication token.

Sample request

curl -X GET https://api.bloq.com/staking/avalanche/fuji/validators \
  -H 'Authorization: Bearer <auth-token>'

Response

Status	Description
200	The list was retrieved.
403	The authorization token is invalid.

Property	Type	Description
(root)	array	The validator data.
[].avalancheNodeId	string	The Avalanche Node ID.
[].chain	string	The validator chain
[].createdAt	string	The validator creation date.
[].id	string	The BloqStake id of the validator.
[].region	string	The validator region.
[].rewardingStakePercentage	string	Percent of stake which thinks this validator is above the uptime requirement.
[].stake	string	The current amount staked during this period.
[].stakingPeriods	array	Array of staking periods of the validator
[].stakingPeriods[].depositTxId	string	Transaction Id of the deposit operation for staking.
[].stakingPeriods[].end	string	End date of the staking.
[].stakingPeriods[].rewardAddresses	string[]	Array of reward addresses.
[].stakingPeriods[].rewards	string	(Optional). Rewards in nAvax.
[].stakingPeriods[].stake	string	The amount staked in nAvax during this period.
[].stakingPeriods[].start	string	Start date of the staking.
[].updatedAt	string	The validator update date.
[].user	string	The user Id.
[].weightedAveragePercentage	string	Stake-weighted average of all observed uptimes for this validator.

Sample response

[
  {
    "avalancheNodeId": "NodeID-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "chain": "mainnet",
    "createdAt": "2022-08-23T20:21:17.725Z",
    "id": "node-0000000-0000-0000-0000-000000000000",
    "region": "us-east-2",
    "rewardingStakePercentage": "45.1234",
    "stake": "0",
    "stakingPeriods": [
      {
        "depositTxId": "aMQx5eMng21SxwXozxikRcMymmts3cRACJhrAEJeruLJpRzgZ",
        "end": "2022-09-30T20:29:13.000Z",
        "rewardAddresses": ["P-fuji1vy5ttya00gkq5h7hlvt6lkpsee8vur0qkjmgkc"],
        "rewards": "10000000",
        "stake": "3000000000",
        "start": "2022-09-05T20:19:44.000Z"
      }
    ],
    "updatedAt": "2022-08-24T10:04:16.142Z",
    "user": "user-00000000-0000-0000-0000-000000000000",
    "weightedAveragePercentage": "45.1234"
  }
]

POST /staking/avalanche/{chain}/validators

Create a new Avalanche validator.

Request

Name	In	Type	Required	Description
Authorization	header	string	yes	The authentication token.
chain	path	path	yes	The validator chain: "mainnet" or "fuji".
region	body	string	no	The region where it will be created. "us-east-2" for EC2, or "k8s" for Kubernetes. Defaults to "us-east-2"

Sample request

curl -X POST https://api.bloq.com/staking/avalanche/mainnet/validators \
  -H 'Authorization: Bearer <auth-token>'
  --data { "region": "us-east-2" }

Response

Status	Description
200	The validator was created.
403	The authorization token is invalid.

Property	Type	Description
(root)	object	The validator data.
.chain	string	The validator chain
.createdAt	string	The validator creation date.
.id	string	The BloqStake Id of the validator.
.user	string	The user Id.
.region	string	The validator region.

Sample responses

Successful response:

{
  "chain": "mainnet",
  "createdAt": "2022-08-23T20:21:17.725Z",
  "id": "node-00000000-0000-0000-0000-000000000000",
  "user": "user-00000000-0000-0000-0000-000000000000",
  "region": "us-east-2"
}

GET /staking/avalanche/{chain}/validators/{id}

Returns one Avalanche validator by its BloqStake Id.

Parameters

Name	In	Type	Required	Description
chain	path	string	yes	The validator's chain: "mainnet" or "fuji".
id	path	string	yes	The validator's Id.
Authorization	header	string	yes	The authentication token.

Sample request

curl -X GET https://api.bloq.com/staking/avalanche/fuji/validators/node-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H 'Authorization: Bearer <auth-token>'

Response

Status	Description
200	The validator was retrieved.
403	The authorization token is invalid.
404	The validator was not found.

Property	Type	Description
(root)	object	The validator data.
.avalancheNodeId	string	The Avalanche Node ID.
.chain	string	The validator chain
.createdAt	string	The validator creation date.
.id	string	The BloqStake Id of the validator.
.region	string	The validator region.
.rewardingStakePercentage	string	Percent of stake which thinks this validator is above the uptime requirement.
.stake	string	The current amount staked during this period.
.stakingPeriods	array	Array of staking periods of the validator
.stakingPeriods[].depositTxId	string	Transaction Id of the deposit operation for staking.
.stakingPeriods[].end	string	End date of the staking.
.stakingPeriods[].rewardAddresses	string[]	Array of reward addresses.
.stakingPeriods[].rewards	string	(Optional). Rewards in nAvax.
.stakingPeriods[].stake	string	The amount staked during this period in nAvax.
.stakingPeriods[].start	string	Start date of the staking.
.updatedAt	string	The validator update date.
.user	string	The user Id.
.weightedAveragePercentage	string	Stake-weighted average of all observed uptimes for this validator.

Sample response

{
  "avalancheNodeId": "NodeID-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "chain": "mainnet",
  "createdAt": "2022-08-23T20:21:17.725Z",
  "id": "node-0000000-0000-0000-0000-000000000000",
  "region": "us-east-2",
  "rewardingStakePercentage": "45.1234",
  "stake": "0",
  "stakingPeriods": [
    {
      "depositTxId": "aMQx5eMng21SxwXozxikRcMymmts3cRACJhrAEJeruLJpRzgZ",
      "end": "2022-09-30T20:29:13.000Z",
      "rewardAddresses": ["P-fuji1vy5ttya00gkq5h7hlvt6lkpsee8vur0qkjmgkc"],
      "rewards": "10000000",
      "stake": "3000000000",
      "start": "2022-09-05T20:19:44.000Z"
    }
  ],
  "updatedAt": "2022-08-24T10:04:16.142Z",
  "user": "user-00000000-0000-0000-0000-000000000000",
  "weightedAveragePercentage": "45.1234"
}

GET /staking/avalanche/billing/report

Returns a billing report of the organization's validators for the period specified, grouped by user. Requires the role auditor or billing.

Parameters

Name	In	Type	Required	Description
accept	header	string	no	The format of the report. Accepts "application/json" (default), "text/csv"
fromDate	query string	string	no	Report's starting date
organization	query string	string	no	Organization to filter the validators. Only valid for billing users
toDate	query string	string	no	Report's end date

Sample request

curl -X GET https://api.bloq.com/staking/avalanche/billing/report/user?fromDate=2023-01-15&toDate=2023-02-25 \
  -H 'Authorization: Bearer <auth-token>'

Response

Status	Description
200	The report was retrieved.
403	The authorization token is invalid or the user has no auditor role.

If the accept header is application/json

Property	Type	Description
(root)	object	The report data.
[].organization	string	The organization Id where the user belongs to.
[].organizationName	string	The organization name the validator belongs to.
[].reportFrom	string	Report's starting date.
[].reportTo	string	Report's end date.
[].user	string	User Id.
[].userEmail	string	The user email.
[].userName	string	The user name.
[].validatorsPerChain	object[]	Validators grouped by chain.
[].validatorsPerChain[].chain	string	The chain, i.e. "mainnet" or "fuji".
[].validatorsPerChain[].fees	string	Amount of fees to deduce for the user.
[].validatorsPerChain[].rewards	string	Amount of rewards in nAvax earned by the user during the period of the report.
[].validatorsPerChain[].rewardsAfterFees	string	Rewards minus fees for the user.
[].validatorsPerChain[].staked	string	Amount that is being staked in nAvax at the end of the report for all validators.
[].validatorsPerChain[].totalActiveValidators	number	Amount of validators that staked during the report period.
[].validatorsPerChain[].totalCurrentValidators	number	Amount of validators that are currently staking.
[].validatorsPerChain[].totalInactiveValidators	number	Amount of validators that did not stake during the report period.
[].validatorsPerChain[].totalWeightedValidators	string	Sum of every day that the validator was staking during the period divided by the number of days of the period.
[].validatorsPerChain[].validatorsActive	object[]	Array of validators that staked during the report's period.
[].validatorsPerChain[].validatorsActive[].activeDays	number	Number of days the validator has been staking during the period.
[].validatorsPerChain[].validatorsActive[].avalancheNodeId	string	Avalanche Id from the network of validators.
[].validatorsPerChain[].validatorsActive[].createdAt	string	Validator's creation date.
[].validatorsPerChain[].validatorsActive[].fees	string	Amount of fees to deduce for the validator.
[].validatorsPerChain[].validatorsActive[].rewards	string	Amount of rewards earned by the validator during the period of the report.
[].validatorsPerChain[].validatorsActive[].rewardsAfterFees	string	Validator's rewards minus fees.
[].validatorsPerChain[].validatorsActive[].runningDays	string	Number of days the validator's been running since its creation until the present day or its deletion.
[].validatorsPerChain[].validatorsActive[].staked	string	Amount that is being staked in nAvax at the end of the report.
[].validatorsPerChain[].validatorsInactive	object []	Array of validators that did not stake during the report's period.
[].validatorsPerChain[].validatorsInactive[].avalancheNodeId	string	Avalanche Id from the network of validators.
[].validatorsPerChain[].validatorsInactive[].createdAt	string	Validator's creation date.
[].validatorsPerChain[].validatorsInactive[].deletedAt	string | null	Validator's deletion date.
[].validatorsPerChain[].validatorsInactive[].runningDays	string	Number of days the validator's been running since its creation until the present day or its deletion.

Sample response

[
  {
    "organization": "org-00000000-0000-5000-b000-000000000000",
    "organizationName": "Org test",
    "reportFrom": "2023-01-27",
    "reportTo": "2023-02-25",
    "user": "user-00000000-0000-4000-00000000000000000",
    "userEmail": "[e-mail]",
    "userName": "Test user",
    "validatorsPerChain": [
      {
        "chain": "mainnet",
        "fees": "28703148",
        "rewards": "717578700",
        "rewardsAfterFees": "688875552",
        "staked": "2000000000",
        "totalActiveValidators": 1,
        "totalCurrentValidators": 0,
        "totalInactiveValidators": 0,
        "totalWeightedValidators": 0.6,
        "validatorsActive": [
          {
            "activeDays": 15,
            "avalancheNodeId": "NodeID-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "createdAt": "2022-12-29T18:07:27.364Z",
            "fees": "28703148",
            "rewards": "717578700",
            "rewardsAfterFees": "688875552",
            "runningDays": 60,
            "staked": "2000000000"
          }
        ],
        "validatorsInactive": []
      },
      {
        "chain": "fuji",
        "fees": "0",
        "rewards": "23331848",
        "rewardsAfterFees": "23331848",
        "staked": "2500000000",
        "totalActiveValidators": 1,
        "totalCurrentValidators": 1,
        "totalInactiveValidators": 1,
        "totalWeightedValidators": 0.5,
        "validatorsActive": [
          {
            "activeDays": 14,
            "avalancheNodeId": "NodeID-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
            "createdAt": "2023-01-04T20:59:35.909Z",
            "fees": "0",
            "rewards": "23331848",
            "rewardsAfterFees": "23331848",
            "runningDays": 54,
            "staked": "2500000000"
          }
        ],
        "validatorsInactive": [
          {
            "avalancheNodeId": "NodeID-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
            "createdAt": "2023-01-04T20:59:35.909Z",
            "runningDays": 54
          }
        ]
      }
    ]
  }
]

If the accept header is text/csv

Property	Type	Description
activeDays	number	Number of days the validator has been staking during the period.
avalancheNodeId	string	Avalanche Id from the network of validators.
chain	string	The chain, i.e. "mainnet" or "fuji".
createdAt	string	Validator's creation date.
deletedAt	string | null	Validator's deletion date.
fees	string	Amount of fees to deduce for the validator.
organization	string	The organization Id where the user belongs to.
organizationName	string	The organization name the validator belongs to.
reportFrom	string	Report's starting date.
reportTo	string	Report's end date.
rewards	string	Amount of rewards earned by the validator during the period of the report.
rewardsAfterFees	string	Validator's rewards minus fees.
runningDays	string	Number of days the validator's been running since its creation until the present day or its deletion.
staked	string	Amount that is being staked in nAvax at the end of the report.
user	string	User Id.
userEmail	string	The user email.
userName	string	The user name.

Sample response

activeDays,avalancheNodeId,chain,createdAt,deletedAt,fees,organization,organizationName,reportFrom,reportTo,rewards,rewardsAfterFees,runningDays,staked,user,userEmail,userName
15,NodeID-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx,mainnet,2022-12-29T18:07:27.364Z,,28703148,org-00000000-0000-5000-b000-000000000000,Org test,2023-01-27,2023-02-25,717578700,688875552,60,2000000000,user-00000000-0000-4000-00000000000000000,[e-mail],Test user
14,NodeID-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,fuji,2023-01-04T20:59:35.909Z,,0,org-00000000-0000-5000-b000-000000000000,Org test,2023-01-27,2023-02-25,23331848,23331848,54,2500000000,user-00000000-0000-4000-00000000000000000,[e-mail],Test user
,NodeID-zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz,fuji,2023-01-04T20:59:35.909Z,,0,org-00000000-0000-5000-b000-000000000000,Org test,2023-01-27,2023-02-25,,,54,,user-00000000-0000-4000-00000000000000000,[e-mail],Test user

DELETE /staking/avalanche/{chain}/validators/{id}

Terminates a validator.

Parameters

Name	In	Type	Required	Description
chain	path	string	yes	The validator's chain: "mainnet" or "fuji".
id	path	string	yes	The validator's Id.
Authorization	header	string	yes	The authentication token.

Sample request

curl -X DELETE https://api.bloq.com/staking/avalanche/fuji/validators/node-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
  -H 'Authorization: Bearer <auth-token>'

Response

Status	Description
204	The validator was deleted.
403	The authorization token is invalid.
404	The validator was not found.
409	The validator is actively staking, and cannot be deleted.

Error responses

All error responses are JSON objects that loosely follow the RFC 7807 specification.

{
  "status": 403,
  "title": "Forbidden",
  "detail": "The authorization token is expired."
}