> For the complete documentation index, see [llms.txt](https://docs.bloq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloq.com/bloq-services/bloqstake/avalanche/api-routes.md). # API Routes Jump to: * [DELETE /staking/avalanche/{chain}/validators/{id}](#delete-staking-avalanche-chain-validators-id) * [GET /staking/avalanche/{chain}/validators](#get-staking-avalanche-chain-validators) * [GET /staking/avalanche/{chain}/validators/{id}](#get-staking-avalanche-chain-validators-id) * [GET /staking/avalanche/billing/report](#get-staking-avalanche-billing-report) * [GET /staking/avalanche/chains](#get-staking-avalanche-chains) * [POST /staking/avalanche/{chain}/validators](#post-staking-avalanche-chain-validators) * [Error responses](#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. | ```shell curl -X GET https://api.bloq.com/staking/avalanche/chains \ -H 'Authorization: Bearer ' ``` ### 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 ```json ["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 ```shell curl -X GET https://api.bloq.com/staking/avalanche/fuji/validators \ -H 'Authorization: Bearer ' ``` ### 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 ```json [ { "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 ```shell curl -X POST https://api.bloq.com/staking/avalanche/mainnet/validators \ -H 'Authorization: Bearer ' --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: ```json { "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 ```shell curl -X GET https://api.bloq.com/staking/avalanche/fuji/validators/node-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \ -H 'Authorization: Bearer ' ``` ### 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 ```json { "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 ```shell curl -X GET https://api.bloq.com/staking/avalanche/billing/report/user?fromDate=2023-01-15&toDate=2023-02-25 \ -H 'Authorization: Bearer ' ``` ### 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 ```json [ { "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": "test@bloq.com", "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,test@bloq.com,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,test@bloq.com,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,test@bloq.com,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 ```shell curl -X DELETE https://api.bloq.com/staking/avalanche/fuji/validators/node-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \ -H 'Authorization: Bearer ' ``` ### 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](https://datatracker.ietf.org/doc/html/rfc7807) specification. ```json { "status": 403, "title": "Forbidden", "detail": "The authorization token is expired." } ```