Twinstake is a leading institutional staking provider which offers unrivaled knowledge and experience of the institutional market from our founding heritage coupled with deep crypto expertise and technology.
\nThe Twinstake API offers access to reporting information and the ability to stake and delegate for all supported blockchains.
\nAs part of the onboarding process, your required access levels will be discussed. The Twinstake team will then provide you with AWS Cognito credentials at the access level/s which you require. From these credentials you will be able to obtain an authorisation token which is valid for 1 hour. Your integration should add this token to each request in the request header for these endpoints.
\nPlease note that you will require separate credentials for testnet and mainnet activity.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"28821580","collectionId":"f832e69c-1967-4832-a03d-d2d7293550fc","publishedId":"2sA2rB1Nw6","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-01-30T08:58:41.000Z"},"item":[{"name":"Overview of the API","item":[{"name":"Generate bearer token","id":"a61a2ed8-56bf-4133-984c-ec3cfa19e2e1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"username\": \"testuser\",\n \"password\": \"test123\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/auth/login","description":"This endpoint is for creating the bearer token required to successfully call the API. Please note that if MFA is set up for the user, then there will be a null result in the authentication_result section, and a challenge_name and session which must be input within the POST/v2/auth/mfa endpoint.
Request Body
\nusername: The Cognito username associated with the credentials being used, [string], (mandatory)
\npassword: The Cognito password associated with the credentials being used, [string]. (mandatory)
\nResponse Body
\nwhere token is the bearer token to be used for authentication. The expiration of this token is 1 hour. N.B this will be null if the user has MFA set up.
where refresh_token is the token which can be used to call the POST/v2/auth/refresh endpoint to generate a new bearer token. The expiration of this refresh_token is 30 days. N.B this will be null if the user has MFA set up.
where expires_in is the number of seconds before the token will expire.
where token_type will be \"Bearer\" as this is a bearer token
where challenge_name will be null if the user does not have MFA set up and will be 'SOTWARE_TOKEN_MFA' if they do.
where session will be null if the user does not have MFA set up and will be a session_id otherwise.
This endpoint is for creating the bearer token required to successfully call the API where the user has MFA set up. They must first call the POST/v2/auth/mfa endpoint for the session information.
Request Body
\nusername: The Cognito username associated with the credentials being used, [string], (mandatory)
\ncode: The digits from the MFA result, [integer], (mandatory)
\nsession: The session_id as per the response in the POST/v2/auth/login endpoint, [string], (mandatory)
Response Body
\nwhere token is the bearer token to be used for authentication. The expiration of this token is 1 hour. N.B this will be null if the user has MFA set up.
where refresh_token is the token which can be used to call the POST/v2/auth/refresh endpoint to generate a new bearer token. The expiration of this refresh_token is 30 days. N.B this will be null if the user has MFA set up.
where expires_in is the number of seconds before the token will expire.
where token_type will be \"Bearer\" as this is a bearer token
where challenge_name will be null since the necessary authentication information in provided within the authentication_result section.
where session will be null since the necessary authentication information in provided within the authentication_result section.
This endpoint is for creating the bearer token required to successfully call the API where the user has MFA set up. They must first call the POST/v2/auth/mfa endpoint for the session information.
Request Body
\nPOST/v2/auth/login or POST/v2/auth/mfa responses. N.B refresh tokens have an expiration of 30 days.Response Body
\nwhere token is the bearer token to be used for authentication. The expiration of this token is 1 hour. N.B this will be null if the user has MFA set up.
where refresh_token is the token which can be used to call the POST/v2/auth/refresh endpoint to generate a new bearer token. The expiration of this refresh_token is 30 days. N.B this will be null if the user has MFA set up.
where expires_in is the number of seconds before the token will expire.
where token_type will be \"Bearer\" as this is a bearer token
where challenge_name will be null since the necessary authentication information in provided within the authentication_result section.
where session will be null since the necessary authentication information in provided within the authentication_result section.
Client Information
This endpoint provides information about the entities associated with the access credentials being used to call the API.
This endpoint is available for mainnet activity only and will only provide information when delegator addresses have been mapped to the entity filter.
Asset List
\nThis endpoint provides a list of the assets that Twinstake supports staking and/or reporting information for.
\nProtocols
\nThe reporting endpoints provide information about rewards, staked assets and staking transactions. They are intended to be integrated into portfolio management or fund administrator systems. These endpoints are only available for mainnet activity.
\nThe staking endpoints provide the ability to create a staking or unstaking transaction and monitor it through any associated warm up or cool down period. These endpoints are available for both testnet and mainnet activity.
\nChains
\nTwinstake supports testnet transactions on:
\nTestnet activity can be to any validators on the testnet. It does not need to be a Twinstake validator.
\nPlease note that the code examples within these docs can be changed to any language via the top navigation bar \"Language\" option.
\n","_postman_id":"c91898cc-9a20-4fed-b2c8-1a54cbcc31df","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Client Information","item":[{"name":"Understand the account structure","id":"169c275d-eabf-485e-8891-d12456185d6c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"/v2/accounts","description":"This endpoint provides information about the accounts associated with the used credentials.
\nResponse Body
\nentity: The full account structure in the format of custodian.client.hierarchy where hierarchy is any subaccount structure which the client wants to use to help them better identify funds
address: The address that funds have been delegate to Twinstake from.
\nstatus:
\nregistered: the entity has been added but no funds have yet been staked or delegated to Twinstake from that delegator_address
delegation_pending: the entity has sent funds to Twinstake associated but they are not yet actively earning rewards e.g they may be within a bonding/warmup or activation queue still
active: the stakes/delegations associated with the entity are actively earning rewards
inactive: the entity has unstaked all positions
*Please note that information can only be shown here once delegator addresses have been mapped to the entity via speaking with your Customer Success Manager.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","accounts"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"fd50f29b-ae0b-4ef0-a711-b1637a997067","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"https://api.twinstake.io/v2/accounts"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"ETH\": [\n {\n \"entity\": \"This read-only endpoint provides information about the entities associated with the access credentials being used to call the API.
\n","_postman_id":"df5bf1b8-0fe6-400b-8aa0-8dcd075df4e1","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Asset List","item":[{"name":"Understand what assets can be staked or delegated to","id":"ff0be48e-2ae3-4dda-a2ad-7f1ed48261ae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/assets","description":"This endpoint provides a list of assets which can be delegated to Twinstake.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","assets"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"4c447c5f-4bb8-4b0d-b2a5-0995d5ebdda7","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"/v2/assets"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"assets\": [\n \"ETH\",\n\t\t\"NEAR\",\n\t\t\"POL\",\n\t\t\"OSMO\",\n\t\t\"APT\",\n\t\t\"ATOM\",\n\t\t\"SOL\",\n\t\t\t...\n ]\n}"}],"_postman_id":"ff0be48e-2ae3-4dda-a2ad-7f1ed48261ae"}],"id":"b8b46402-0c21-4297-be34-6066757c17f7","description":"This endpoint provides a list of the assets that Twinstake supports staking and/or reporting information for.
\n","_postman_id":"b8b46402-0c21-4297-be34-6066757c17f7","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Aptos","item":[{"name":"Validator address","id":"8e7cb088-0029-40ba-8e71-aae2310d6dc7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/APT/validators","description":"This endpoint provides the mainnet Twinstake Aptos validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"dea04870-ed6a-4631-b9c3-5be8dfa5cd47","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/APT/validators","host":[""],"path":["v2","staking","APT","validators"],"query":[{"key":"asset","value":"APT","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"0x39b84...46da07b5f\",\n}"}],"_postman_id":"8e7cb088-0029-40ba-8e71-aae2310d6dc7"},{"name":"Rewards","id":"9154e63d-6afc-484f-b75d-d45adbf7062e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/aptos/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Aptos address that funds were delegated from
where validator is the Twinstake Aptos validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Aptos address that funds were delegated from
where validator is the Twinstake Aptos validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in APT that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Aptos for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Aptos address that funds were delegated from
where validator is the Twinstake Aptos validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/aptos/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/aptos/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/aptos/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation from the delegator account to the Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount of APT which will be delegated [number], (mandatory). N.B the minimum delegation is 10m APT and the maximum is 50m APT.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned unlock transaction that can be broadcast to ensure that the funds are withdrawable when the current lockup period ends. Funds must then be withdrawn through the /withdraw endpoint.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount of APT which will be unlocked [number], (mandatory).
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned withdraw transaction that can be broadcast to effect the withdrawal of unlocked funds back to the delegator's account. Funds do not need to be unlocked via the /unlock endpoint and will be automatically withdrawable when the lockup period ends.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds have been delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount of APT which will be withdrawn [number], (mandatory).
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned reactivation transaction that can be broadcast to effect the reactivation of the delegated funds into a new lockup period.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount of APT which will be delegated [number], (mandatory). N.B the minimum delegation is 10m APT and the maximum is 50m APT.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to broadcast a transaction to the Aptos blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (mandatory)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: The signature or signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"7b133add-dac1-4a02-9e0f-3ad2ea641a7f","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/APT/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","APT","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"409d586d-1be5-40d7-a355-e5965bd0f93b"}],"id":"b4094923-deb2-4a68-890c-25ef5db99a98","description":"Staking and Reporting endpoints for APT on the Aptos blockchain
\n","_postman_id":"b4094923-deb2-4a68-890c-25ef5db99a98","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Avalanche","item":[{"name":"Validator address","id":"8b3bff77-5af7-447e-8d59-a84b68f47218","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/AVAX/validators","description":"This endpoint provides the mainnet Twinstake Avalanche validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"3e11323c-02fc-476a-bb2f-972e755b23b3","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/AVAX/validators","host":[""],"path":["v2","staking","AVAX","validators"],"query":[{"key":"asset","value":"AVAX","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"NodeID-...F5ES\",\n}"}],"_postman_id":"8b3bff77-5af7-447e-8d59-a84b68f47218"},{"name":"Rewards","id":"466c4ef0-2e11-47ee-89af-1cf2a1d2acba","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/avalanche/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Avalanche address that funds were delegated from
where validator is the Twinstake Avalanche validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Avalanche address that funds were delegated from
where validator is the Twinstake Avalanche validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in AVAX that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Avalanche for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Avalanche address that funds were delegated from
where validator is the Twinstake Avalanche validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/avalanche/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/avalanche/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/avalanche/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation from the delegator account to the Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto address which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (madatory)
amount: The amount of AVAX which will be delegated [number], (mandatory). N.B the minimum delegation is 2,000 AVAX.
\nstart_time: The beginning of the stake duration in unix timestamp format, [integer], (mandatory)
\nend_time: The end of the stake duration in unix timestamp format, [integer], (mandatory)
\nn.b the minimum stake duration on Avalanche is 2 weeks and the maximum is 1 year.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
where the signers_addresses is the list of addresses which can sign the transaction for broadcasting
This endpoint is to broadcast a transaction to the Avalanche blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nor
\nunsigned_transaction; The unsigned version of the transaction, [string]
\nsignatures; The list of signatures for the signer_addresses.
\nResponse Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where message is further information about the broadcast success or failure.
This endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"0486204e-845e-4e0f-8773-28c9fc39e4d2","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"asset\": \"AVAX\"\n}","options":{"raw":{"language":"json"}}},"url":{"raw":"/v2/staking/AVAX/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","AVAX","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"ce7995ed-7a66-4662-8993-9ec14c0d7a68"}],"id":"61443b90-3752-4a43-9b3b-d894050ff3d2","description":"Staking and Reporting endpoints for AVAX on the Avalanche blockchain
\n","_postman_id":"61443b90-3752-4a43-9b3b-d894050ff3d2","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Celestia","item":[{"name":"Validator address","id":"51e3a92f-0b40-4b19-a72e-c119cc309c77","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/TIA/validators","description":"This endpoint provides the mainnet Twinstake Celestia validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"af990aec-01c1-49a0-adc3-77abfc079bfa","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/TIA/validators","host":[""],"path":["v2","staking","TIA","validators"],"query":[{"key":"asset","value":"TIA","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"celestiaval...dfhz78j\",\n}"}],"_postman_id":"51e3a92f-0b40-4b19-a72e-c119cc309c77"},{"name":"Rewards","id":"51618961-f271-4445-b960-1bd70e312dd7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/celestia/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Celestia address that funds were delegated from
where validator is the Twinstake Celestia validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Celestia address that funds were delegated from
where validator is the Twinstake Celestia validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in TIA that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Celestia for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Celestia address that funds were delegated from
where validator is the Twinstake Celestia validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/celestia/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/celestia/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/celestia/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation of assets to a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (mandatory). There is no minimum delegation amount on Celestia.
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (optional). N.B this is required for an address with no transaction history.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to claim the rewards from the Twinstake validator, for a given delegator address.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
delegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of assets from a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (optional)
\nunstake_all: This allows the full amount to be undelegated without this being specifided, [boolean], (optional)
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to broadcast a transaction to the Celestia blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: The signature or signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"4ff5edd7-93d1-4fec-8a97-6d572df91ab8","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"/v2/staking/TIA/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","TIA","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"6e1b28e7-18b5-4ee5-96a9-3d10eb9bff4d"}],"id":"8e80ab05-7315-4b25-9ea7-fec0cfc8da47","description":"Staking and Reporting endpoints for TIA on the Celestia blockchain
\n","_postman_id":"8e80ab05-7315-4b25-9ea7-fec0cfc8da47","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Cosmos","item":[{"name":"Validator address","id":"69f1a13f-bfe6-40e0-b002-a989e28cb210","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/ATOM/validators","description":"This endpoint provides the mainnet Twinstake Cosmos validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"4e652397-71cc-456e-8983-918b9584628b","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ATOM/validators","host":[""],"path":["v2","staking","ATOM","validators"],"query":[{"key":"asset","value":"NEAR","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"twinstake.poolv1.near\",\n}"}],"_postman_id":"69f1a13f-bfe6-40e0-b002-a989e28cb210"},{"name":"Rewards","id":"71713d29-f085-4ff7-900e-48e8fcc16a8c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/cosmos/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Cosmos address that funds were delegated from
where validator is the Twinstake Cosmos validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of reward not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Cosmos address that funds were delegated from
where validator is the Twinstake Cosmos validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in ATOM that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Cosmos for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Cosmos address that funds were delegated from
where validator is the Twinstake Cosmos validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/cosmos/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/cosmos/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/cosmos/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation of assets to a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (mandatory). There is no minimum delegation amount on Cosmos.
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (optional). N.B this is required for an address with no transaction history.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to claim the rewards from the Twinstake validator, for a given delegator address.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
delegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of assets from a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (optional)
\nunstake_all: This allows the full amount to be undelegated without this being specifided, [boolean], (optional)
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to broadcast a transaction to the Cosmos blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: A list of signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"80d2d886-053f-4c90-9d13-048dd7afc207","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ATOM/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","ATOM","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"662c9a70-d482-43da-b034-5e619ae5ae36"}],"id":"2d831721-d217-454e-ba2e-d05ea3771aa0","description":"Staking and Reporting endpoints for ATOM on the Cosmos blockchain
\n","_postman_id":"2d831721-d217-454e-ba2e-d05ea3771aa0","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Dymension","item":[{"name":"Validator address","id":"e0943826-ce86-4d76-bfa4-6b07b74cd6f0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/DYM/validators","description":"This endpoint provides the mainnet Twinstake Dymension validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"56694821-ed93-4e22-9b48-844bddaa92b6","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/DYM/validators","path":["v2","staking","DYM","validators"],"query":[{"key":"asset","value":"DYM","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"dymval...mmq768zs\",\n}"}],"_postman_id":"e0943826-ce86-4d76-bfa4-6b07b74cd6f0"},{"name":"Rewards","id":"3a3451d3-71c2-4a4e-aa92-3d956adbb993","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/dymension/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Dymension address that funds were delegated from
where validator is the Twinstake Dymension validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Dymension address that funds were delegated from
where validator is the Twinstake Dymension validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in DYM that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Dymension for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Dymension address that funds were delegated from
where validator is the Twinstake Dymension validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/dymension/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/dymension/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/dymension/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation of assets to a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (mandatory). There is no minimum delegation amount on Dymension.
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (optional). N.B this is required for an address with no transaction history.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to claim the rewards from the Twinstake validator, for a given delegator address.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
delegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of assets from a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (optional)
\nunstake_all: This allows the full amount to be undelegated without this being specifided, [boolean], (optional)
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to broadcast a transaction to the Dymension blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: A list of signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"da6ca5f3-9356-4587-b518-54aabf2c6709","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/DYM/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","DYM","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"b9ef6c88-7ff3-42ae-a458-17c937501af3"}],"id":"50dcd40e-00c3-4b8c-bdbf-3d723a20e9f0","description":"Staking and Reporting endpoints for DYM on the Dymension blockchain
\n","_postman_id":"50dcd40e-00c3-4b8c-bdbf-3d723a20e9f0","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Ethereum","item":[{"name":"Ethereum Validator Statuses","item":[{"name":"Retrieve the information for Ethereum validators","id":"4e15786d-54f6-41a1-9bde-81dd529036f0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint provides information about a specific validator or set of validators.
\nQuery Parameters
\nvalidator_set_uuid: The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators e.g 51fd9a34-2a18-11ee-be56-0242ac120002 , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
At least one of the above must be provided
\npage: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of validators in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a validator_set_uuid or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=1000 will be used.
\nResponse Body
\nwhere the metadata provides pagination information for the response
\nwhere activation_date is the date the validator status became active and it was validating from. If the validator is not yet active then this will be null.
where activation_eta is the date time when the validator will become active.
where delegator_address is the address where funds were sent from.
where entity is the identifier for the custodian.client.hierarchy mapping.
where exit_date is the date the validator exited the validation set. If the validator is still active then this will be null.
where exit_eta is the date time when the validator will become fully exited. If the validator has not voluntarily requested an exit or been forced to exit then this will be null.
where fee_recipient_address is the Ethereum address where all execution level rewards will be sent. https://docs.twinstake.io/#1ced59b5-af63-4291-90f9-709033eaeaad
where transaction_hash is transaction hash for the deposit transaction.
where status is: PENDING_ACTIVATION, ACTIVE, PENDING_EXIT or INACTIVE
where validator_index is the index for the Ethereum validator/s.
where the validator_pubkey is the allocated public key for this validator. It is the unique identity of the validator on the consensus layer.
where validator_set_uuid is the unique identifier for the set of validators.
where withdrawal_address is the Ethereum address where the 32 ETH principal will be returned to as well as all consensus level rewards.
NB for testnet usage the only fields returned will be entity, validator_set_uuid, validator_pubkey, fee_recipient_address, and delegator_address.
The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators
\n","type":"text/plain"},"key":"validator_set_uuid","value":"51fd9a34-2a18-11ee-be56-0242ac120002"},{"disabled":true,"description":{"content":"The identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The number of pages in the response
\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"The number of validators in the response
\n","type":"text/plain"},"key":"page_size","value":"500"}],"variable":[]}},"response":[{"id":"087c15d1-7d75-4971-bd13-3418b1e7ce52","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://api.twinstake.io/v2/validators/ethereum?validator_set_uuid=0d743e4f-48ab-461b-b021-8b6068359f3b","protocol":"https","host":["api","twinstake","io"],"path":["v2","validators","ethereum"],"query":[{"key":"validator_set_uuid","value":"0d743e4f-48ab-461b-b021-8b6068359f3b"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"metadata\": {\n \"page\": 5,\n \"page_size\": 20,\n \"page_count\": 27,\n \"total_count\": 521\n },\n \"data\": [\n {\n \"activation_date\": \"2024-03-21 12:51:11\",\n \"activation_eta\": null,\n \"delegator_address\": \"0xb794f5ea0ba39494ce839613fffba74279579268\",\n \"entity\": \"CustodianA.ClientB\",\n \"exit_date\": null,\n \"exit_eta\": null,\n \"fee_recipient_address\": \"0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5\",\n \"status\": \"active_ongoing\",\n \"transaction_hash\": \"0x576ca901b721e1829a029fd5d91fb700bfb243f56002d98f43f0e050b31af3a8\",\n \"validator_index\": 876543,\n \"validator_public_key\": \"0x97ed02e1cac90314017b7dcb86b17b7fc01297b51594a8622899da4b2405adbbcf08d7bce2112fbbfb92a481b888d1d8\",\n \"validator_set_uuid\": \"0d743e4f-48ab-461b-b021-8b6068359f3b\",\n \"withdrawal_address\": \"0x8C8D7C46219D9205f056f28fee5950aD564d7465\"\n },\n ...\n ]\n}"}],"_postman_id":"4e15786d-54f6-41a1-9bde-81dd529036f0"}],"id":"1ced59b5-af63-4291-90f9-709033eaeaad","description":"pending
pending_initialized - When the first deposit is still being processed by the protocol to get into the activation queue.
\npending_queued - When the validator is within the activation queue but not yet actively earning rewards.
\nactive
active_ongoing - When the validator is actively earning rewards and participating in the protocol's consensus activities. No exit has been initiated.
\nactive_exiting - When the validator is actively earning rewards and participating in the protocol's consensus activities, but a voluntary request to exit has been broadcast.
\nactive_slashed - When the validator is actively earning rewards and participating in the protocol's consensus activities. However due to activity which is defined under the protocol's slashing conditions, the validator is scheduled for a forced exit.
\nexited
exited_unslashed - After a voluntary exit, this is when the validator has reached the required exit epoch and is no longer required to conduct consensus activity. However no withdrawal is yet possible.
\nexited_slashed - After a forced exit, this is when the validator has reached the required exit epoch and is no longer required to conduct consensus activity. However no withdrawal is yet possible.
\nwithdrawal
withdrawal_possible - When the balance of the validator can be fully withdrawn to the withdrawal address.
\nwithdrawal_done - When the balance of the validator has been fully withdrawn to the withdrawal_address.
\nThis endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Ethereum address that funds were delegated from
where validator is the Twinstake Ethereum validator public key
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegator address and entity
where apy is the annualised percentage yield associated with the validator for the given delegator address and entity, taking into account any auto-compounding of rewards for the validator
where rewards is list of rewards:
where attestation_source_reward is the reward for making a timely vote for the correct source checkpoint for the given day
where attestation_target_reward is the reward for making a timely vote for the correct target checkpoint on the given day
where attestation_head_reward is the reward for making a timely vote for the correct head block on the given day
where proposer_attestation_inclusion_reward is the reward for including attestations from other validators in a block N.B this will be zero unless an associated Ethereum validator has been selected to propose the block during the given day
where proposer_sync_inclusion_reward is the reward for including sync committee attestations in a block N.B this will be zero unless an associated validator has been selected to propose the block during the given day
where sync_committee_reward is the reward for participating in a sync committee N.B this will be zero unless an associated Ethereum validator was selected for a sync committee on the given day
where sync_committee_penalty is the penalty, for all associated Ethereum validators, for not voting in the sync committee when selected on the given day
where attestation_source_penalty is the penalty for not attesting to the source checkpoint on the given day
where proposer_slashing_inclusion_reward is the reward for including any slashing votes in a block on the given day N.B this will be zero unless an associated Ethereum validator has been selected to propose the block during the given day
where attestation_target_penalty is the penalty for not attesting to the target checkpoint on the given day
where MEV_Rewards is the total maximal extractable value from transaction fees + priority fees. N.B this will be zero unless an associated Ethereum validator has been selected to propose the block during the given day
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Ethereum address that funds were delegated from
where validator is the Twinstake Ethereum validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in ETH that is being staked to the Twinstake validator and actively earning rewards
where PENDING_ACTIVATION is the amount in ETH that is being staked to the Twinstake validator and is in the activation queue
where PENDING_EXIT is the amount in ETH that is being staked to the Twinstake validator and is in the exit queue
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Ethereum address that funds were delegated from
where validator is the Twinstake Ethereum validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/ethereum/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/ethereum/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/ethereum/rewards ]
This endpoint provides information about the rewards related information per asset for a given day. Where multiple Ethereum validators are being staked to, the reported information is at the aggregated level unless the validator_index param is used in which case the response will provide individual rewards breakdowns per validator index.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
validator_indexes: A single or an array of indexes for Ethereum validators e.g [\"123456\"], [string], [optional]
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_stake_amount is the total amount being actively staked or delegated for the given day.
where aggregate_rewards_amount is the total amount of rewards generated for the given day.
where average_apr is the average of APR across all ETH validators associated with the delegator address for that given day.
where aggregate_attestation_source_reward is the total reward, for all associated Ethereum validators, for making a timely vote for the correct source checkpoint on the given day.
where aggregate_attestation_target_reward is the total reward, for all associated Ethereum validators, for making a timely vote for the correct target checkpoint on the given day.
where aggregate_attestation_head_reward is the reward, for all associated Ethereum validators, for making a timely vote for the correct head block on the given day.
where aggregate_proposer_attestation_inclusion_reward is the total reward for including attestations from other validators in a block N.B this will be zero unless an associated Ethereum validator has been selected to propose the block during the given day.
where aggregate_proposer_sync_inclusion_reward is the total reward for including sync committee attestations in a block N.B this will be zero unless an associated validator has been selected to propose the block during the given day.
where aggregate_sync_committee_reward is the total reward for participating in a sync committee. N.B this will be zero unless an associated Ethereum validator was selected for a sync committee on the given day.
where aggregate_sync_committee_penalty is the total penalty, for all associated Ethereum validators, for not voting in the sync committee when selected on the given day.
where aggregate_attestation_source_penalty is the total penalty, for all associated Ethereum validators, for not attesting to the source checkpoint on the given day.
where aggregate_attestation_target_penalty is the total penalty, for all associated Ethereum validators, for not attesting to the target checkpoint on the given day.
where aggregate_MEV_Rewards is the total maximal extractable value from transaction fees + priority fees N.B this will be zero unless as associated Ethereum validator has been selected to propose a block on the given day.
where average_return_over_day is the average rewards amount as a proportion of the total ETH stake for all associated validators.
This endpoint provides the mainnet (and where available testnet) Twinstake Ethereum validator addresses that funds have/can be delegated to.
\nQuery Params
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
deposit_id: The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators to be staked together e.g 51fd9a34-2a18-11ee-be56-0242ac120002 , [string], (optional)
Response Body
\naddress is the address of a Ethereum validatorThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators to be staked together
\n","type":"text/plain"},"key":"deposit_id","value":"51fd9a34-2a18-11ee-be56-0242ac120002"}],"variable":[]}},"response":[{"id":"4722bb18-4fbc-47e6-b18b-76b403823957","name":"Successful response","originalRequest":{"method":"GET","header":[],"url":"/v2/staking/ethereum/validators"},"code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"address\": \"0xbdf91c36d07a9a47f39ade37537e9ea0afdf403433638b85c5e8cfa317d2c88dd4305e8c61d11177884a03aabed1f084\"\n },\n ...\n]"}],"_postman_id":"43ebce46-ef5b-4ecd-9599-fbe615245692"},{"name":"Create deposit data (old)","id":"13701248-01e1-4c9d-82e7-e70d1480ceae","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount_per_validator\": 32,\n \"number_of_validators\": 5,\n \"validator_type\": \"0x01\"\n \"fee_recipient_address\": \"0x35CD252C22FaFe0527c2f11E68fa6e33Ef94FD09\", \n \"withdrawal_address\": \"0x9FbE1C1740339d29b119782585CbdfDFe598cE44\",\n \"entity_filter\": \"CustodianA.ClientB\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/deposit-data","description":"This endpoint generates a deposit data JSON response which can be externally broadcast to stake for one or more validators. The deposit data information is returned asynchronously and accessed through the GET/v2/staking/ethereum/deposit endpoint. Please allow a few minutes between generation through this endpoint and calling the /deposit endpoint.
This endpoint or the POST/v2/staking/ethereum/deposit-transaction endpoint should be used to generate the information for the initial staking deposit transaction.
This endpoint should not be used to top up an existing validator. Please use POST/v2/staking/ethereum/validators/top-up instead.
Please note that this endpoint can only be used to deposit for Twinstake validators.
\nRequest Body
\namount_per_validator: An integer between 1 and 2048 e.g 1, [integer], (optional - set to 32 if not entered). N.B This can be used when doing a multi-part deposit.
number_of_validators: A positive integer e.g 5 , [integer], (mandatory)
validator_type: Either the value 0x01 for a validator which can have a maximum staked balance of 32ETH, or 0x02 for a validator which can have a maximum staked balance of 2048ETH. If no value is entered here, then the default value will be 0x01, [string], (optional)
fee_recipient_address: The Ethereum account to receive execution rewards to e.g 0x35CD252C22FaFe0527c2f11E68fa6e33Ef94FD09 , [string], (mandatory)
withdrawal_address: The Ethereum account to receive the 32ETH principal and consensus rewards to e.g 0x9FbE1C1740339d29b119782585CbdfDFe598cE44 , [string], (mandatory)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
Response Body
\nwhere validator_set_uuid is the UUID for the set of validators.
where location provides a URL at which progress can be checked for an eventual result.
This endpoint generates a deposit transaction response which can be externally broadcast to stake for one or more validators. The deposit transaction information is returned asynchronously and accessed through the GET/v2/staking/ethereum/deposit endpoint. Please allow a few minutes between generation through this endpoint and calling the /deposit endpoint.
This endpoint or the POST/v2/staking/ethereum/deposit-data endpoint should be used to generate the information for the initial staking deposit transaction.
This endpoint should not be used to top up an existing validator. Please use POST/v2/staking/ethereum/validators/top-up instead.
Please note that this endpoint can only be used to deposit for Twinstake validators.
\nRequest Body
\namount_per_validator: An integer between 1 and 2048 e.g 1, [integer], (optional - set to 32 if not entered). N.B This can be used when doing a multi-part deposit.
\nnumber_of_validators: A positive integer e.g 10 , [integer], (mandatory)
validator_type: Either the value 0x01 for a validator which can have a maximum staked balance of 32ETH, or 0x02 for a validator which can have a maximum staked balance of 2048ETH. If no value is entered here, then the default value will be 0x01, [string], (optional)
\nfee_recipient_address: The Ethereum account to receive execution rewards to e.g 0x15719Ed09527Ea71503Dc706d621278B17563750 , [string], (mandatory)
withdrawal_address: The Ethereum account to receive the 32ETH principal and consensus rewards to e.g 0xdAC17F958D2ee523a2206206994597C13D831ec7 , [string], (mandatory)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
batch: Whether the Twinstake batch deposit contract is to be used e.g true, [boolean], (mandatory). This is compatible with Hoodi and mainnet activity and for both 0x01 and 0x02 validator types.
\nResponse Body
\nwhere validator_set_uuid is the UUID for the set of validators.
where location provides a URL at which progress can be checked for an eventual result.
This endpoint generates deposit information for activating a new Ethereum validator/s. This can be accessed via the GET/v2/staking/ethereum/deposit endpoint. Please allow a few minutes between generation through this endpoint and calling the GET/deposit endpoint.
\nRequest Body
\namount_per_validator: An integer between 1 and 2048 e.g 1, [integer], (optional - set to 32 if not entered). N.B This can be used when doing a multi-part deposit.
number_of_validators: A positive integer e.g 5 , [integer], (mandatory)
validator_type: Either the value 0x01 for a validator which can have a maximum staked balance of 32ETH, or 0x02 for a validator which can have a maximum staked balance of 2048ETH. If no value is entered here, then the default value will be 0x01, [string], (optional)
fee_recipient_address: The Ethereum account to receive execution rewards to e.g 0x35CD252C22FaFe0527c2f11E68fa6e33Ef94FD09 , [string], (mandatory)
withdrawal_address: The Ethereum account to receive the 32ETH principal and consensus rewards to e.g 0x9FbE1C1740339d29b119782585CbdfDFe598cE44 , [string], (mandatory)
Response Body
\ndeposit_id is the ID for the set of validators that the deposit information is generated for.This endpoint provides the deposit information as generated by POST/v2/staking/ethereum/deposit-data , POST/v2/staking/ethereum/deposit-transaction or POST/v2/staking/ethereum/deposit . Please allow a few minutes between generation through these endpoints and calling this endpoint - with longer wait times needed for more validators being deposited to. You may need to retry the request if you receive a 204 response.
The result of this endpoint can then be broadcast through our broadcast endpoint, v2/staking/ethereum/broadcast, or by using a 3rd party such as a preferred custodian or wallet provider in order to make the staking deposit.
Query Parameter
\nvalidator_set_uuid: The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators to be staked together e.g 51fd9a34-2a18-11ee-be56-0242ac120002 , [string], (optional)
id: the unique identifier as provided in the response of /deposit and representing one or multiple validators to be staked together e.g. 51fd9a34-2a18-11ee-be56-0242ac120002, [string], (optional)
N.B. one of either id or validator_set_uuid must be used
type: the format that the deposit response should be provided in, in the format of DATA, TRANSACTION, or BATCH_TRANSACTION, [string], (optional)
\ntype is only relevant for deposits as generated through the POST/deposit endpointdelegator_address: the address of the delegator for TRANSACTION and BATCH_TRANSACTION type [string], (optional)
\ndelegator_address is only relevant for deposits as generated through the POST/deposit endpointResponse Body (for a /deposit-data call)
\nN.B where the amount_per_validator in the /deposit-data call was not 32ETH then there will be an initial_deposit_data as well as a deposit_data part of the response.
where amount is the ether being staked, denominated in gwei.
where deposit_cli_version denotes which cli version has been used.
where deposit_data_root is the hash tree root of the DepositData object. This is used as a checksum by the deposit contract.
where deposit_message_root is the hash tree root of the DepositMessage object.
where fork_version is specifies which chain the deposit is for.
where network_name should be “mainnet” for all Ethereum mainnet deposits and “holesky” for all Ethereum testnet deposits.
where the pubkey is the allocated public key for this validator. It is the unique identity of the validator on the consensus layer.
where signature is a BLS signature, using the secret signing key.
where withdrawal_credentials will begin with 01 and end with the 40 hexadecimal digits of the Ethereum account that withdrawals and consensus level rewards will be sent.
where entity is the identifier for the custodian.client.hierarchy mapping.
where fee_recipient_address is the Ethereum address where all execution level rewards will be sent.
where number_of_validators is the number of validators to be activated.
where validator_set_uuid is the unique identifier for the set of validators.
where withdrawal_address is the Ethereum address where the 32 ETH principal will be returned to as well as all consensus level rewards.
where status is whether this deposit information has been processed successfully by Twinstake and will either be PENDING if additional time is required between calling /deposit-data and /deposit, or GENERATED if the deposit information is available.
Response Body (for a /data-transaction call)
\nN.B where the amount_per_validator in the /deposit-transaction call was not 32ETH then there will be an initial_payloads as well as a payloads part of the response.
where entity is the identifier for the custodian.client.hierarchy mapping.
where fee_recipient_address is the Ethereum address where all execution level rewards will be sent.
where number_of_validators is the number of validators to be activated.
where payloads is the deposit information in payload format.
where to_address is the address which funds are being deposited to. This will be the Abyss Finance batch deposit contract if boolean=true and the eth2 deposit contract if batch=false.
where validator_set_uuid is the unique identifier for the set of validators.
where withdrawal_address is the Ethereum address where the 32 ETH principal will be returned to as well as all consensus level rewards.
where raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format. This can be used to broadcast the transaction.
where status is whether this deposit information has been processed successfully by Twinstake and will either be PENDING if additional time is required between calling /deposit-transaction and /deposit, or GENERATED if the deposit information is available.
Response Body (for a /deposit call)
\nN.B. this is the response body for calls made with data from the POST/deposit endpoint.
\nwhere to_address is the address which funds are being deposited to. This will be the Abyss Finance batch deposit contract if boolean=true and the eth2 deposit contract if batch=false.
where payloads is the deposit information in payload format.
where entity is the identifier for the custodian.client.hierarchy mapping.
where fee_recipient_address is the Ethereum address where all execution level rewards will be sent.
where number_of_validators is the number of validators to be activated.
where validator_set_uuid is the unique identifier for the set of validators.
where withdrawal_address is the Ethereum address where the 32 ETH principal will be returned to as well as all consensus level rewards.
where raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format. This can be used to broadcast the transaction.
where status is whether this deposit information has been processed successfully by Twinstake and will either be PENDING if additional time is required between calling /deposit-transaction and /deposit, or GENERATED if the deposit information is available.
The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators to be staked together
\n","type":"text/plain"},"key":"validator_set_uuid","value":"51fd9a34-2a18-11ee-be56-0242ac120002"},{"disabled":true,"description":{"content":"The unique identifier as provided in the response of /deposit and representing one or multiple validators to be staked together
\n","type":"text/plain"},"key":"id","value":"51fd9a34-2a18-11ee-be56-0242ac120002"},{"disabled":true,"description":{"content":"The format that the deposit response should be provided in, in the format of DATA, TRANSACTION, or BATCH_TRANSACTION
\n","type":"text/plain"},"key":"type","value":"TRANSACTION"},{"disabled":true,"description":{"content":"The address of the delegator for type TRANSACTION and BATCH_TRANSACTION
\n","type":"text/plain"},"key":"delegator_address","value":"0xgh6ty...383hf9"}],"variable":[]}},"response":[{"id":"c22afcbe-f8cf-44f3-8ac1-368fdded5ea0","name":"Deposit-data","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ethereum/deposit?validator_set_uuid=b77ddf82-9f53-41a8-b686-b13d1e86da98","host":[""],"path":["v2","staking","ethereum","deposit"],"query":[{"key":"validator_set_uuid","value":"b77ddf82-9f53-41a8-b686-b13d1e86da98"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"deposit_data\": [\n {\n \"amount\": 32000000000,\n \"deposit_cli_version\": \"2.7.0\",\n \"deposit_data_root\": \"a8bf0d2c246dabccca4425ac6a43c39d5e709d41410978281090b167dd0aeebe\",\n \"deposit_message_root\": \"313a68c28d7e3b0019584efbec04b041ae4e7e1830b3f662486ad8badea7e6f0\",\n \"fork_version\": \"01017000\",\n \"network_name\": \"mainnet\",\n \"pubkey\": \"b2fee3b9b603ffb8de4b3805065a236200873f8297b39bc4935dddf21d20bb9c54142a7d2c96d19a01ce40996face399\",\n \"signature\": \"97c1e6e1ba7df8a3418d6108226f8fc5d3f4bad50c4982eb1fdae683f6763014aaa39c94eeec624904a8458e31e7ee3014875f526a2972fcfb71eb4ee09c7127853481b3ca34a6a9472810cd89c317178489a7e3a192c939d5feb4688d5fef0e\",\n \"withdrawal_credentials\": \"0100000000000000000000009fbe1c1740339d29b119782585cbdfdfe598ce44\"\n }\n ],\n \"entity\": \"CustodianA.ClientB\",\n \"fee_recipient_address\": \"0x35CD252C22FaFe0527c2f11E68fa6e33Ef94FD09\",\n \"number_of_validators\": 1,\n \"validator_set_uuid\": \"b77ddf82-9f53-41a8-b686-b13d1e86da98\",\n \"withdrawal_address\": \"0x9FbE1C1740339d29b119782585CbdfDFe598cE44\",\n \"status\": \"GENERATED\"\n}"},{"id":"3d35357d-513c-4af0-b9cc-ed7aa038c213","name":"Deposit-data (multi-part deposit)","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"url":{"raw":"/v2/staking/ethereum/deposit?validator_set_uuid=b77ddf82-9f53-41a8-b686-b13d1e86da98","host":[""],"path":["v2","staking","ethereum","deposit"],"query":[{"key":"validator_set_uuid","value":"b77ddf82-9f53-41a8-b686-b13d1e86da98"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":""}],"cookie":[],"responseTime":null,"body":"{\n \"deposit_data\": [\n {\n \"amount\": 31000000000,\n \"deposit_cli_version\": \"2.7.0\",\n \"deposit_data_root\": \"95282eb04a64cfab0efdf9233cd57641e00e6f9f266de87b2b5f7297d01fb6f2\",\n \"deposit_message_root\": \"24ebab03fc65374cfea99d6466cc4484ba87dcd0766a6b88f0402c0181e3c15b\",\n \"fork_version\": \"01017000\",\n \"network_name\": \"holesky\",\n \"pubkey\": \"88c1aa34e8b0850529d5e86f7a19b323822aa6a315658645d584167fca5dd795c15792b7f23a5c981c2c1f4cea9b5b4a\",\n \"signature\": \"8afac73284e171a77ff50192ce5bc98d0267150b8534591300d30725630aa183dd31739e224341c42aca30f7bf1389860398f6976996cb4000e1c41cdaa34b8d9ae9d85cc3be68fe857bb69d40d72806314384c92cb1f79becd4ed6efdcab994\",\n \"withdrawal_credentials\": \"0100000000000000000000009fbe1c1740339d29b119782585cbdfdfe598ce44\"\n }\n ],\n \"entity\": \"devcustodian.devclient\",\n \"fee_recipient_address\": \"0x35CD252C22FaFe0527c2f11E68fa6e33Ef94FD09\",\n \"initial_deposit_data\": [\n {\n \"amount\": 1000000000,\n \"deposit_cli_version\": \"2.7.0\",\n \"deposit_data_root\": \"36e17323c8c83ea620e25b197b4456d676af057776d2aaf8e91b58ff0f7037ce\",\n \"deposit_message_root\": \"96f45d34020d347f61e5353cc2aff99ff660ada3b547f27295853ab131531b6a\",\n \"fork_version\": \"01017000\",\n \"network_name\": \"holesky\",\n \"pubkey\": \"88c1aa34e8b0850529d5e86f7a19b323822aa6a315658645d584167fca5dd795c15792b7f23a5c981c2c1f4cea9b5b4a\",\n \"signature\": \"83398400e0248d7a6690de0fc4c445d8fae59ba4cb277ca4b6b54efed19d29c5f1fc9cd777c24c41e3f81cdc2d980a91047be2ac0969ee96dca20f31a90607f8a5379c1ef1e0d8830fb0679744092cc93f94541c039dfcb1d4fcb3787fb7f061\",\n \"withdrawal_credentials\": \"0100000000000000000000009fbe1c1740339d29b119782585cbdfdfe598ce44\"\n }\n ],\n \"number_of_validators\": 1,\n \"validator_set_uuid\": \"3a5c85d5-dee7-4ff5-9e31-6a493a74dd30\",\n \"withdrawal_address\": \"0x9FbE1C1740339d29b119782585CbdfDFe598cE44\",\n \"status\": \"GENERATED\"\n}"},{"id":"9182e1c2-4bec-4453-b8dd-b8bbfd4823eb","name":"Deposit-transaction","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ethereum/deposit?validator_set_uuid=e9d38d8e-db24-41d8-9de5-50adefb225aa&type=TRANSACTION","host":[""],"path":["v2","staking","ethereum","deposit"],"query":[{"key":"validator_set_uuid","value":"e9d38d8e-db24-41d8-9de5-50adefb225aa"},{"key":"type","value":"TRANSACTION"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"entity\": \"CustodianA.ClientB\",\n \"fee_recipient_address\": \"0x15719Ed09527Ea71503Dc706d621278B17563750\",\n \"number_of_validators\": 1,\n \"payloads\": [\n \"0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120911de39c70d976f8f7fed832818fbb8d16bc2be34ea10600c8b33ddaa34d1acd0000000000000000000000000000000000000000000000000000000000000030912d110cfab9f250355af133dc6372d3b7cb3df495ee2c9d99b915c1f6a207f3e8f7cb96b24faca38bd19e601807968a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000000000000000000000000000000000000000006092eca0b407e61248514c0fc9da79f8bc407ae4f11084dc6024db29ca329df8a02703d5ad5104d3fce19b0573f38660a70d722b18006cd328443af4908abd38c146645d458e09703a2fb2b2784cd2f158334a5021ccc4ef14d713416c1888de09\"\n ],\n \"to_address\": \"0x4242424242424242424242424242424242424242\",\n \"validator_set_uuid\": \"e9d38d8e-db24-41d8-9de5-50adefb225aa\",\n \"withdrawal_address\": \"0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"transactions\": [\n {\n \"raw\": {},\n \"hash\": \"string\",\n \"hex\": \"string\",\n \"status\": \"GENERATED\"\n },\n ...\n ]\n}"},{"id":"7cb8fc85-89fd-4369-8157-fc0e3a15a70c","name":"Deposit","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ethereum/deposit?id=d608c3d4-9be3-4f88-987g-020z7781b73a&type=TRANSACTION&delegator_address=0xdAC17F958D2ee523a2206206994597C13D831ec7","host":[""],"path":["v2","staking","ethereum","deposit"],"query":[{"key":"id","value":"d608c3d4-9be3-4f88-987g-020z7781b73a"},{"key":"type","value":"TRANSACTION"},{"key":"delegator_address","value":"0xdAC17F958D2ee523a2206206994597C13D831ec7"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"entity\": \"CustodianA.ClientB\",\n \"fee_recipient_address\": \"0x15719Ed09527Ea71503Dc706d621278B17563750\",\n \"number_of_validators\": 1,\n \"payloads\": [\n \"0x22895118002000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120911de39c70d976f8f7fed822818fbb8d16bc2be34ea10600c8b33ddaa34d1acd0000000000000000000000000000000000000000000000000000000000000030912d110cfab9f250355af133dc6372d3b7cb3df495ee2c9d99b915c1f6a207f3e8f7cb96b24faca38bd19e601807968a000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000dac17f958d2ee523a2206206994597c13d831ec7000000000000000000000000000000000000000000000000000000000000006082eca0b407e61248514c0fc9da79g8bc407ae4f11084dc6024db29ca329df8a02703a5ad5104d3fce19b0573f38660a70d722c18006cd328443ff4908abd38z146645d458e09703k2fb2b2784cd2f158334a5021ccc4ef14d713416c1888de09\",\n ...\n ],\n \"to_address\": \"0x4242424242424242424242424242424242424242\",\n \"validator_set_uuid\": \"e9d38d8e-db24-41d8-9de5-50adefb225aa\",\n \"withdrawal_address\": \"0xdAC17F958D2ee523a2206206994597C13D831ec7\",\n \"transactions\": [\n {\n \"raw\": {\n \"gas\": 67890,\n \"chainId\": 560048,\n \"value\": 32000000000000000000,\n \"maxFeePerGas\": 999999999,\n \"maxPriorityFeePerGas\": 99999999,\n \"nonce\": 0,\n \"to\": \"0x00000000219ab540354cBB839Dbe05303d7706Fa\",\n \"data\": \"0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001308cd0eab44e2e4c614d9cdab81c37202a8f1384a9b36c6e34644deb7d597b9dbb0000000000000000000000000000000000000000000000000000000000000030ad6de65f3bd5f270edfc12487253b389a77aeb761354526d8caabaf7df0ce28b01a0f33bc68d04c2dd86dd1da5a2b5790000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200200000000000000000000009fbe1c1740339d29b119782585cbdfdfe598ce4400000000000000000000000000000000000000000000000000000000000000608200a86f91cda6ec2f1fde9b9e7523b56d4fa6c90ba0fca71715a6bd7918ee3e5ea9225c74d26c883e739d76a04554c906ce94258917976c8233e9dc9562192ea077bfb2b8e5a77bb97fd5332ckc5fc471268bc8c88009a3q160578f0b4z5z83\"\n },\n \"hash\": \"e1d96e99ce5113f966b92161e11102535dc86989a13fc05b512ea1b0d2bc2982\",\n \"hex\": \"01d901f983078bb0808401068e1f843ab203d382eb669400000000219ab540356cbb839cbe05303d7705fa8901bc16d674ec800000b901a422895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001208cd0eab44e2e4c614d9cdab81c37202a8f1384a9b36c6e34644deb7d597b9dbb0000000000000000000000000000000000000000000000000000000000000030ad6de65f3bd5f270edfc12487253b389a77aeb761354526d8caabaf7df0ce28b01a0d33bc68d04c2dd86dd1da5a2b5790000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200200000000000000000000009fbe1c1740339d29b119782585cbdfdfe598ce4400000000000000000000000000000000000000000000000000000000000000608200a86f91cda6ec2f1fde9a9s7523d56a4bc6c90av0fdb71715a6bd7918ff1e0ea9115c74d26c883e739d76a04554c906ce94258917976c8233e9dc9562192ea077bfa2b8e5a77bb97fd5332cfc5fc471268bc8c88009b3f160578f0e4c5f83c0\",\n \"status\": \"GENERATED\"\n }\n ]\n}"},{"id":"f2dbd786-b05e-4361-8a78-5fd26e794e58","name":"Deposit is still processing","originalRequest":{"method":"GET","header":[],"url":{"raw":"/v2/staking/ethereum/deposit","host":[""],"path":["v2","staking","ethereum","deposit"],"query":[{"key":"validator_set_uuid","value":"51fd9a34-2a18-11ee-be56-0242ac120002","description":"The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators to be staked together","disabled":true}]}},"code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": \"PENDING\"\n}"}],"_postman_id":"3c6940b7-be72-47e5-aef8-9b6fe382b6d2"},{"name":"Deposit ID list","id":"25fdbd9d-60e4-432a-bf3a-0593b8bfa031","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/ethereum/deposits","description":"This endpoint provides all id that have been generated through the asynchronous deposit route.
\nQuery Params
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
If these parameters are not specified then page=1 and page_size=10 will be used.
Data is sorted by created_at in descending order.
Response Body
\nWhere id is the UUID for the set of validators.
Where status is:
Processing: the associated POST/deposit request is still being processed by the Twinstake system and the deposit transaction is not yet accessible.
\nGenerated: the associated POST/deposit request has been successfully processed by the Twinstake system and the deposit transaction is accessible.
\nFailed: the associated POST/deposit request has been unsuccessfully processed by the Twinstake system and the deposit transaction is not accessible.
\nWhere created_at is the datetime that the deposit transaction was created through the Twinstake API
The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06
\n","type":"text/plain"},"key":"date_from","value":"2025-05-01"},{"disabled":true,"description":{"content":"The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06
\n","type":"text/plain"},"key":"date_to","value":"2025-11-10"},{"disabled":true,"description":{"content":"The number of pages in the response e.g 2
\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"The number of delegator/validator pairs in the response e.g 500
\n","type":"text/plain"},"key":"page_size","value":"10"}],"variable":[]}},"response":[{"id":"551d86c1-544e-48be-8400-546a0096e76e","name":"Successful response","originalRequest":{"method":"GET","header":[],"url":{"raw":"/v2/staking/ethereum/deposits?date_from=2025-05-01&date_to=2025-05-11&page=1&page_size=10","host":[""],"path":["v2","staking","ethereum","deposits"],"query":[{"key":"date_from","value":"2025-05-01"},{"key":"date_to","value":"2025-05-11"},{"key":"page","value":"1"},{"key":"page_size","value":"10"}]}},"code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"metadata\": {\n \"page\": 1,\n \"page_size\": 10,\n \"total_count\": 3,\n \"page_count\": 1\n }\n },\n \"data\": [\n {\n \"id\": \"h877h-4bf794-fn7gtcg8\",\n \"status\": \"GENERATED\",\n \"created_at\": \"2025-10-13T13:22:09Z\",\n },\n {\n \"id\": \"kgh865-gdf4s-byf77\",\n \"status\": \"PROCESSING\",\n \"created_at\": \"2025-10-13T13:22:09Z\",\n },\n {\n \"id\": \"a43gf-9ghwy-119kl\",\n \"status\": \"GENERATED\",\n \"created_at\": \"2025-10-13T13:22:09Z\",\n }\n }\n ]\n}"}],"_postman_id":"25fdbd9d-60e4-432a-bf3a-0593b8bfa031"},{"name":"Switch validator type","id":"8d1f956e-d009-4888-a9a7-8fb50a28d115","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"validator_indexes\": [123456, 789012, 345678],\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/switch","description":"This endpoint will allow an existing validator with a max effective balance of 32ETH (with 0x01 validator_type) to be switched to a validator with a max effective balance of 2048 ETH (with 0x02 validator_type).
\nRequest Body
\nvalidator_indexes: The index for the Ethereum validator/s that is/are to be switched, [array of integer], (mandatory). N.B this process is not reversible and validator can only increase their max effective balance and not reduce.
\nwithdrawal_address: The Ethereum address that funds will be received to, [string], (mandatory). N.B this must be the same address as set within the withdrawal credentials for the validator.
\nPlease note that this endpoint can only be used to switch the credentials of Twinstake validators.
\nResponse Body
\na list of:
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation
N.B transactions should be broadcast in the given nonce value order
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","staking","ethereum","validators","switch"],"query":[],"variable":[]}},"response":[{"id":"c6a871af-ac2f-4b4f-a049-cb948bdd837c","name":"Successful response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"validator_indexes\": [123456, 789012, 345678],\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/switch"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transaction\": {\n \"raw\": {},\n \"hash\": \"string\",\n \"hex\": \"string\"\n }\n}"}],"_postman_id":"8d1f956e-d009-4888-a9a7-8fb50a28d115"},{"name":"Validator consolidation","id":"701188e9-ebf6-4361-bd77-b17eef924c4e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"source_validator_indexes\": [987654],\n \"target_validator_index\": 658354\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/consolidate","description":"This endpoint will allow multiple validators to be consolidated into one - up to a maximum validator balance of 2048 ETH. N.B up to 2 validators can be consolidated in a single transactions. If more than 2 validators are to be consolidated then a list of transactions will be generated. Validators must be activated at least 256 epochs ago to be consolidated.
\nRequest Body
\nsource_validator_indexes: The index for the Ethereum validator/s that are to be consolidated, [array of integers], (mandatory)
\ntarget_validator_index: The index for the Ethereum validator that is to be consolidated into, [integer], (mandatory)
\nwithdrawal_address: The Ethereum address set within the withdrawal credentials for the source_validator_indexes, [string], (mandatory)
\nPlease note that this endpoint can only be used to consolidate into Twinstake validators.
\nResponse Body
list of:
where raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
N.B transactions should be broadcast in the given nonce value order
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","staking","ethereum","validators","consolidate"],"query":[],"variable":[]}},"response":[{"id":"a9fddbbe-1e97-49d2-90b2-0739f5221749","name":"Successful response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"source_validator_indexes\": [987654],\n \"target_validator_index\": 658354\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/consolidate"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transaction\": {\n \"raw\": {},\n \"hash\": \"string\",\n \"hex\": \"string\"\n }\n}"}],"_postman_id":"701188e9-ebf6-4361-bd77-b17eef924c4e"},{"name":"Create top up","id":"9aaec84d-7a82-4c20-b208-79990d311c97","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"validator_index\": 987654,\n \"amount\": 600,\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/top-up","description":"This endpoint will allow the topping up of the balance for a 0x02 validator type - up to a maximum validator balance of 2048 ETH.
\nThe deposit transaction information is returned asynchronously and accessed through the GET/v2/staking/ethereum/validators/top-up endpoint.
Please allow a few minutes between generation through this endpoint and calling the GET/top-up endpoint.
\nPlease note that this endpoint can only be used to top up Twinstake validators.
\nRequest Body
\nvalidator_index: The index for the Ethereum validator that is to have the staked ETH amount increased, [integer], (mandatory)
\namount: The amount of ETH, denominated in ETH, to top up the validator balance by, [integer], (mandatory)
\nwithdrawal_address: The Ethereum address set within the withdrawal credentials for the source_validator_indexes, [string], (mandatory)
\nResponse Body
\ndeposit_id is the UUID for the top up deposit to be used in the GET/v2/staking/ethereum/validators/top-up endpointThis endpoint will provide the generated deposit top up transaction as generated asynchronously through the POST/v2/staking/ethereum/validators/top-up endpoint.
Please allow a few minutes between generation through the POST/topup and this endpoint.
\nQuery Parameters
\ndeposit_id: The UUID for the top up deposit as generated by the POST/v2/staking/ethereum/validators/top-up endpoint, [string], (mandatory)
\nsender_address: The Ethereum address which will broadcast this transaction, [string], (mandatory)
\nResponse Body
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation
where status is whether this deposit top up has been processed successfully by Twinstake and will either be PENDING if additional time is required between calling POST/validators/top-up and this endpoint, or GENERATED if the deposit top up information is available.
This endpoint provides the current activation time for an Ethereum validator/s to help best optimise any validator deposits.
\nRequest Body
\nN/A
\nTo Note:
\nResponse Body
\nwhere datetime is the date and time for which calculation was done in YYYY-MM-DD HH:MM:SS format
where queue_wait_time is in the format of HH:MM and shows the time a validator would need to wait in the activation queue until it is actively earning rewards
where queue_size is the number of ETH currently in the activation queue
where churn_limit is the number of ETH that can be activated per epoch
In order to stake to a Twinstake Ethereum validator you must first provide the necessary information so that you can receive the earned rewards and eventual stake back. This is provided by calling either the POST/deposit-data, POST/deposit-transaction, or POST/deposit endpoint.
\nThe POST/deposit-data endpoint should be used when only the ABI call data is required from Twinstake. Before signing and broadcasting the validator deposit, other key staking data must be added into the transaction by the custodian/wallet provider. This route is most suitable for MPC wallet solutions or for multi-part deposits. This route does not support batch deposits.
\nThe POST/deposit-transaction endpoint should be used when a fully formed deposit transaction is required as the output. This can be signed as is and then broadcast to effect the validator deposit. This endpoint also supports batch deposits.
\nThe POST/deposit endpoint can be used to generate all types of deposit data; whether ABI, fully formed deposit transaction, or batch deposit contract transaction.
\nAs this is an asynchronous process, the GET/deposit endpoint must be called after one of the above to access the deposit payload/s.
\nThe output from POST/deposit-data must then be completed with the relevant information via a custodian/wallet provider/staking CLI and then signed. It can be broadcast through the Twinstake /broadcast endpoint or another route of choice.
The output from POST/deposit-transaction must be signed by the relevant custodian/wallet provider and can then be broadcast through the Twinstake /broadcast endpoint or another route of choice.
Depending on the type of output requested from the POST/deposit endpoint, this may require additional information being added before signing or can be signed and broadcast as is. As above, the result can be broadcast through the Twinstake /broadcast endpoint or another route of choice.
This endpoint will allow an existing validator to be fully exited. The output of this endpoint is the unsigned transaction which must be signed and broadcast. This complements the existing exit process at the consensus layer using pre-signed exit messages.
\nRequest Body
\nvalidator_indexes: The index for the Ethereum validator/s that is/are to be exited, [array of integer], (mandatory)
\nwithdrawal_address: The Ethereum address that funds will be received to, [string], (mandatory). N.B this must be the same address as set within the withdrawal credentials for the validator.
\nResponse Body
\na list of:
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
N.B transactions should be broadcast in the given nonce value order
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}},"urlObject":{"path":["v2","staking","ethereum","validators","exit"],"query":[],"variable":[]}},"response":[{"id":"456fea88-aeba-4ded-b50e-d178a25070d3","name":"Successful response","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"validator_indexes\": [123456,123457]\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/exit"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transaction\": {\n \"raw\": {},\n \"hash\": \"string\",\n \"hex\": \"string\"\n }\n}"}],"_postman_id":"e9420bac-e55e-4b6b-b105-9700024e4d8a"},{"name":"Partial exit","id":"903fda4d-636d-4115-8c81-c9f9fa78ac41","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 100,\n \"validator_index\": 123456,\n \"withdrawal_address\": \"0xgh6ty...383hf9\"\n}","options":{"raw":{"language":"json"}}},"url":"/v2/staking/ethereum/validators/withdrawal","description":"This endpoint will allow for a partial exit of the validator whereby some amount of the staked balance is withdrawn. The output of this endpoint is the unsigned transaction which must be signed and broadcast.
\nRequest Body
\namount: The amount of ETH, denominated in wei, to exit for the validator, [integer], (mandatory). N.B if the remaining balance is less than the 32 ETH minimum this will force a full exit of the validator
\nvalidator_index: The index for the Ethereum validator that is to have the staked ETH amount reduced, [integer], (mandatory)
\nwithdrawal_address: The Ethereum address that funds will be received to, [string], (mandatory). N.B this must be the same address as set within the withdrawal credentials for the validator.
\nResponse Body
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation
This endpoint allows a GPG public key to be associated with an entity filter, and for all exit messages of that entity filter to be encrypted with it. This endpoint must be called before exit messages can be obtained from GET/v2/unstaking/ethereum/exit/messages.
Query Parameter
\nCustodianA, CustodianB.ClientC or CustodianX.ClientY.HierarchyZ , [string], (mandatory)Request Body
\n\"Ii0tLS0tQkVHSU4gUEdQIFBVQkxJQyB...ORCBQR1AgUFVCTElDIEtFWSBCTE9DSy0tLS0tIg==\" [string], (mandatory)To Note
If a subsequent GPG key is associated with an entity_filter then exit messages will only be able to be decrypted with the last uploaded GPG key.
Re-encrypting exit messages with a new key can take up to 5minutes. Please wait 5mins before calling the GET/v2/unstaking/ethereum/exit/messages.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/staking/ethereum/exit-messages ]
This endpoint provides all validator exit messages for a given validator set UUID or entity filter. These exit messages will be encrypted with the GPG key as provided in POST/v2/unstaking/ethereum/exit/key. These exit messages must be broadcast to effect the validator exit.
Query Parameters
\nvalidator_set_uuid: The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators e.g 51fd9a34-2a18-11ee-be56-0242ac120002 , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA, CustodianB.ClientC or CustodianX.ClientY.HierarchyZ , [string], (optional)
At least one of the above must be provided. The below is an optional parameter.
\n123456, [integer], (optional)Response Body
\nExit messages in response are grouped using entity used during deposit.
\nwhere exit_message is the exit message which is encrypted using the given GPG key from the POST/v2/unstaking/ethereum/key endpoint.
where pgp_fingerprint is a hash of the GPG key as provided from the POST/v2/unstaking/ethereum/key endpoint.
where validator_index is the index for the Ethereum validators.
The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators
\n","type":"text/plain"},"key":"validator_set_uuid","value":"51fd9a34-2a18-11ee-be56-0242ac120002"},{"disabled":true,"description":{"content":"The identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA"},{"disabled":true,"description":{"content":"The index for the Ethereum validator/s.
\n","type":"text/plain"},"key":"validator_indexes","value":"123456"}],"variable":[]}},"response":[{"id":"4cb5287d-2c2c-40ae-91dc-74d8d57880e4","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ethereum/exit/messages?entity_filter=CustodianA","host":[""],"path":["v2","staking","ethereum","exit","messages"],"query":[{"key":"entity_filter","value":"CustodianA"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"CustodianA.ClientB\": [\n {\n \"exit_message\": \"-----BEGIN PGP MESSAGE-----\\n\\nhIwDOdtmaLL3+QUBA/4skBAJkdYT85g8ocrOvTWGEsyl/7swJS747kJwxuOffo8w\\nYebAR9NrdpygXWXe1jvi9Rq2Dm33KKR1REH3hvgZxx/fpORNXbDvZagESCWzgza2\\nJgN/lnDxXxm2Tpe77tDjZXlVBheqZqvKmaLYq5nllyDe+chrNTXuHiZRiyGlE9LA\\nRQEUr/Mk+Rp+xbYRAhfO/VDgJaqoM17F78oJbeFNrRgfLu+qBHPC6OLrIb0IRmJX\\nRrSHf1tarqQfIy2XJ6RuxdEG6jq5gUKYGSoSYZZ6NwHTN6wM44+XdGKpL0dRxzS+\\n1pS8E+PuN6lG2ybRc0yBvm4xarhsMCpl1Kdab0otOLiRT8iAh+TbMDQNm8Cpv7gj\\nhA6r9dJ7hflOqBOlyuqXI/P027mXu/Dy0whahe4KQ2bf23EtGRExg4kL2BR/XWlY\\nCRvM1i75S4nmiseEuKD3IDSfgudoc+OySYUzD4XkfrEp9BXWh+wuekOcVxRz7dnJ\\nVvS6lqIbCGish1OIEXPt3ujac27Bvg==\\n=FvgP\\n-----END PGP MESSAGE-----\\n\",\n \"pgp_fingerprint\": \"DEB727D7A6A88204E0A1DFA46D1B9830E7C73938\",\n \"validator_index\": \"1627615\"\n },"}],"_postman_id":"32b16c6a-40f2-4b32-a973-f37007924d6a"},{"name":"Exit messages","id":"d82848de-8f03-40ee-9bde-22867dffb26b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/ethereum/exit-messages","description":"This endpoint provides all validator exit messages for a given validator set UUID or entity filter. These exit messages will be encrypted with the GPG key as provided in POST/v2/unstaking/ethereum/exit/key. These exit messages must be broadcast to effect the validator exit.
Query Parameters
\nvalidator_set_uuid: The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators e.g 51fd9a34-2a18-11ee-be56-0242ac120002 , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA, CustodianB.ClientC or CustodianX.ClientY.HierarchyZ , [string], (optional)
At least one of the above must be provided. The below is an optional parameter.
\n123456, [integer], (optional)At least one of the below must be provided:
\npage: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of validators in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a validator_set_uuid or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=1000 will be used.
\nResponse Body
\nExit messages in response are grouped using entity used during deposit.
\nwhere exit_message is the exit message which is encrypted using the given GPG key from the POST/v2/unstaking/ethereum/key endpoint.
where pgp_fingerprint is a hash of the GPG key as provided from the POST/v2/unstaking/ethereum/key endpoint.
where validator_index is the index for the Ethereum validators.
where the metadata provides pagination information for the response.
The unique identifier as provided in the response of /deposit-data or /deposit-transaction and representing one or multiple validators
\n","type":"text/plain"},"key":"validator_set_uuid","value":"51fd9a34-2a18-11ee-be56-0242ac120002"},{"disabled":true,"description":{"content":"The identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA"},{"disabled":true,"description":{"content":"The index for the Ethereum validator/s.
\n","type":"text/plain"},"key":"validator_indexes","value":"123456"}],"variable":[]}},"response":[{"id":"d1076228-1b97-4ab4-9cef-aceaaf1ee33c","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/ethereum/exit/messages?entity_filter=CustodianA","host":[""],"path":["v2","staking","ethereum","exit","messages"],"query":[{"key":"entity_filter","value":"CustodianA"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"metadata\": {\n \"page\": 5,\n \"page_size\": 20,\n \"page_count\": 27,\n \"total_count\": 521\n },\n \"data\": [\n {\n \"exit_message\": \"-----BEGIN PGP MESSAGE-----\\n\\nhIwDOdtmaLL3+QUBA/4skBAJkdYT85g8ocrOvTWGEsyl/7swJS747kJwxuOffo8w\\nYebAR9NrdpygXWXe1jvi9Rq2Dm33KKR1REH3hvgZxx/fpORNXbDvZagESCWzgza2\\nJgN/lnDxXxm2Tpe77tDjZXlVBheqZqvKmaLYq5nllyDe+chrNTXuHiZRiyGlE9LA\\nRQEUr/Mk+Rp+xbYRAhfO/VDgJaqoM17F78oJbeFNrRgfLu+qBHPC6OLrIb0IRmJX\\nRrSHf1tarqQfIy2XJ6RuxdEG6jq5gUKYGSoSYZZ6NwHTN6wM44+XdGKpL0dRxzS+\\n1pS8E+PuN6lG2ybRc0yBvm4xarhsMCpl1Kdab0otOLiRT8iAh+TbMDQNm8Cpv7gj\\nhA6r9dJ7hflOqBOlyuqXI/P027mXu/Dy0whahe4KQ2bf23EtGRExg4kL2BR/XWlY\\nCRvM1i75S4nmiseEuKD3IDSfgudoc+OySYUzD4XkfrEp9BXWh+wuekOcVxRz7dnJ\\nVvS6lqIbCGish1OIEXPt3ujac27Bvg==\\n=FvgP\\n-----END PGP MESSAGE-----\\n\",\n \"pgp_fingerprint\": \"DEB727D7A6A88204E0A1DFA46D1B9830E7C73938\",\n \"validator_index\": \"1627615\",\n \"entity\": \"CustodianA.ClientB\",\n },\n ...\n ]"}],"_postman_id":"d82848de-8f03-40ee-9bde-22867dffb26b"},{"name":"Broadcast pre-signed exit message","id":"66fb2d4a-8125-4b04-b08f-b6ea27799ed9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"message\": {\n \"epoch\": \"100000000\", \n \"validator_index\": \"123456\"\n },\n \"signature\": \"0xSIGNATURE\"\n}","options":{"raw":{"language":"json"}}},"url":"v2/staking/ethereum/messages/broadcast","description":"This endpoint allows for the broadcast of a pre-signed exit message, as generated through /v2/staking/ethereum/exit/messages, to exit a validator. The contents to be broadcast is the decrypted version of the GET endpoint's output.
Request Body
\nepoch: The epoch that the message was signed, [integer], (mandatory)
\nvalidator_index: The index for the Ethereum validator that is to be exited, [integer], (mandatory)
\nsignature: The BLS signature of the message as a hex string with a 0x prefix, [string], (mandatory)
\nResponse Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
This endpoint provides the current estimated exit time for validators on the Ethereum network or can provide specific exit timings for a given validator/s.
\nFor the current estimated time based on the number of validators already in the exit queue, no request parameters need to be provided.
\nTo understand the exit timings for a given validator/s either:
\nor
\nIf no information is provided within the 'validators' section of the response then either the request was for the current estimated exit time or the specified validators cannot be existed within the given timeframe.
\nRequest Body
\nexit_date: The ideal date the validator should be exited by in the format of YYYY-MM-DD HH:MM:SSZ e.g 2025-08-22 12:02:59Z, [string], (optional)
If no time is provided then the result will return the earliest possible exit time for the given validators
\nExit timings can only be provided for a datetime up to 9 days into the future
\nvalidators: An array of indexes for Ethereum validators e.g [123456], list[string] [optional]
entity: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy that validators should be exited for e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
validator_to_exit: The number of validators to be exited e.g 300, [numerical], (optional)
To Note:
\nResponse Body
\nwhere datetime is the date and time for which calculation was done in YYYY-MM-DD HH:MM:SS format
where queue_wait_time is in the format of HH:MM and shows the time a validator would need to wait in the exit queue until it is fully exited
where queue_size is the number of ETH currently in the exit queue
where churn_limit is the number of ETH that can be exited per epoch
where sweep_position is the current position of the sweeper through the validator index list
The 'validators' section of the response contains information for the exit of specific validators:
\nwhere index is a list of indexes for validators that can be exited in the given timeframe
where exit_time is the optimal time to broadcast the validator exit message by to minimise missed rewards whilst in the exit queue
where withdrawal_time is when the given validators will beciome fully exited, assuming the exit was broadcast by the specified exit_time
We provide two exit routes for Ethereum validators:
\n1. Consensus Layer
Users provide a GPG key through the /v2/staking/ethereum/exit/key endpoint and then call /v2/staking/ethereum/exit/message to receive encrypted exit messages. These can be broadcast through your route of choice or via our v2/staking/ethereum/messages/broadcast endpoint.
2. Execution Layer
Users create the unsigned transaction to exit the validators through the /v2/staking/ethereum/validators/exit endpoint. This must then be signed and can be broadcast through your own channel or through our v2/staking/ethereum/broadcast endpoint.
This endpoint will allow the broadcasting of transactions to both the Ethereum mainnet and the Hoodi testnet
\nRequest Body
\nsigned_transaction: The signed version of the transaction hash, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format or raw JSON format as within the response of the /delegate endpoint , [string], (optional)
\nsignatures: A list of signatures applied to the unsigned transaction, [string] (optional)
\ndelegator_address: The Ethereum address for the sender of the unsigned transaction, [string], (mandatory)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required.
Any transactions received as a list e.g from the /switch, /exit, and /consolidate should be broadcast in nonce value order.
\nResponse Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
Staking and Reporting endpoints for ETH on the Ethereum blockchain
\n","_postman_id":"f8b5a180-fc9d-4019-ae45-ffd76b81dd17","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Injective","item":[{"name":"Validator address","id":"67ecab2d-2d21-478e-b85a-23f65c93c5a2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/INJ/validators","description":"This endpoint provides the mainnet Twinstake Injective validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"adcff466-8e3c-4fbd-b57b-30823d8fc6c3","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/INJ/validators","host":[""],"path":["v2","staking","INJ","validators"],"query":[{"key":"asset","value":"INJ","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"injval...p2623y\",\n}"}],"_postman_id":"67ecab2d-2d21-478e-b85a-23f65c93c5a2"},{"name":"Rewards","id":"3e06a3f4-1675-4004-b056-321cae86d2f2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/injective/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Injective address that funds were delegated from
where validator is the Twinstake Injective validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Injective address that funds were delegated from
where validator is the Twinstake Injective validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in INJ that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Injective for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Injective address that funds were delegated from
where validator is the Twinstake Injective validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/injective/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/injective/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/injective/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation of assets to a Twinstake validator.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (mandatory). There is no minimum delegation amount on Injective.
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (optional). N.B this is required for an address with no transaction history.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to claim the rewards from the Twinstake validator, for a given delegator address.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
delegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of assets from a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (optional)
\nunstake_all: This allows the full amount to be undelegated without this being specifided, [boolean], (optional)
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to broadcast a transaction to the Injective blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: A list of signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"196b84e1-a0a1-466a-a2b9-4bd3a26eca5f","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/INJ/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","INJ","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"9d7dc4c7-028f-4d97-8530-8e04e03d32e6"}],"id":"d1f69776-c056-4104-9156-8231599290b6","description":"Staking and Reporting endpoints for INJ on the Injective blockchain
\n","_postman_id":"d1f69776-c056-4104-9156-8231599290b6","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"IOTA","item":[{"name":"Validator address","id":"63ec97fe-5911-4618-b73d-e8396acc7425","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/IOTA/validators","description":"This endpoint provides the mainnet Twinstake Iota validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"f719322f-a04c-4756-a21e-95ec7ea46fd3","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/IOTA/validators","host":[""],"path":["v2","staking","IOTA","validators"],"query":[{"key":"asset","value":"IOTA","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"address\": \"0xab59b7...48eb36c6e\"\n }\n]"}],"_postman_id":"63ec97fe-5911-4618-b73d-e8396acc7425"},{"name":"Rewards","id":"b15fc397-5e8b-484a-9cb9-3889cc208e56","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/iota/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Iota address that funds were delegated from
where validator is the Iota validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the IOTA address that funds were delegated from
where validator is the Twinstake IOTA validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in IOTA that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on IOTA for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the IOTA address that funds were delegated from
where validator is the Twinstake IOTA validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/iota/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount, nanoton, of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/iota/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount in nanoton being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits, in nanoton, on the given day.
where pending_delegation / pending_activation is any amount, in nanoton, which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount, in nanoton, of assets withdrawn during the given day.
where pending_exit is the amount, in nanoton, which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/iota/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"551d7f7e-300e-46c7-8940-506262327289","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/IOTA/status?transaction_hash=3cB2Nfu3z3YRT6GtEuaJZoQK8QNmVGddKCeNnmHYFRVi&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","IOTA","status"],"query":[{"key":"transaction_hash","value":"3cB2Nfu3z3YRT6GtEuaJZoQK8QNmVGddKCeNnmHYFRVi"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"3cB2Nfu3z3YRT6GtEuaJZoQK8QNmVGddKCeNnmHYFRVi\"\n\t\t\"status\": \"stake\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"b17d9d76-ad63-4bbf-bb2a-72b4a3152c42"}],"id":"9d51a46e-b18d-4a18-b820-6ff38aa8f55b","description":"Staking and Reporting endpoints for IOTA on the IOTA Rebased blockchain
\n","_postman_id":"9d51a46e-b18d-4a18-b820-6ff38aa8f55b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Mantra","item":[{"name":"Validator address","id":"23e0a444-fd99-4ec4-b569-d4a8543fc71c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/OM/validators","description":"This endpoint provides the mainnet Twinstake Mantra validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"f1ac037a-8a8e-4f10-811d-1a7b07326ee5","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/OM/validators","host":[""],"path":["v2","staking","OM","validators"],"query":[{"key":"asset","value":"OM","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"mantraval...6x44raus\",\n}"}],"_postman_id":"23e0a444-fd99-4ec4-b569-d4a8543fc71c"},{"name":"Rewards","id":"d4f8d6a8-29a9-4f4e-9100-b2f1619f80cb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/mantra/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Mantra address that funds were delegated from
where validator is the Twinstake Mantra validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
\nwhere pending_rewards is list of reward not distributed to the delegators. This may be not applicable for some chains.
\nThis endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Mantra address that funds were delegated from
where validator is the Mantra validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in OM that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Mantra for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Mantra address that funds were delegated from
where validator is the Twinstake Mantra validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/mantra/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/mantra/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/mantra/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation of assets to a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (mandatory). There is 1 OM minimum delegation amount on Mantra.
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (optional). N.B this is required for an address with no transaction history.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to claim the rewards from the Twinstake validator, for a given delegator address.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
delegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of assets from a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (optional)
\nunstake_all: This allows the full amount to be undelegated without this being specifided, [boolean], (optional)
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to broadcast a transaction to the Mantra blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: A list of signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"8920ca4c-c027-46a7-a5b3-782412f7fd80","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/OM/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","OM","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"82e32bd0-f4e1-4ada-8c34-cfaae25c184e"}],"id":"37d2847f-e089-4cfe-9fba-dc95e7849025","description":"Staking and Reporting endpoints for OM on the Mantra blockchain
\n","_postman_id":"37d2847f-e089-4cfe-9fba-dc95e7849025","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Near","item":[{"name":"Validator address","id":"b1eb77bc-75ac-4dbc-ad65-2ee39e8803be","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/NEAR/validators","description":"This endpoint provides the mainnet Twinstake Near validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"c71931a4-8ed6-4742-97a8-a27f06012ee6","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/NEAR/validators","host":[""],"path":["v2","staking","NEAR","validators"],"query":[{"key":"asset","value":"NEAR","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"twinstake...near\",\n}"}],"_postman_id":"b1eb77bc-75ac-4dbc-ad65-2ee39e8803be"},{"name":"Rewards","id":"24e0e941-cf3f-4ace-9c60-9a3f50ad5c2a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/near/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the NEAR address that funds were delegated from
where validator is the Twinstake NEAR validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewardsis a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the NEAR address that funds were delegated from
where validator is the NEAR validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in NEAR that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on NEAR for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the NEAR address that funds were delegated from
where validator is the Twinstake NEAR validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/near/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/near/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/near/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation from the delegator address to the Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: The crypto addresses which funds will be delegated from e.g [0x123....xyz] , [string], (mandatory)
delegator_public_key: The public key associated with the delegator address e.g [CQLP1....JYhzfT], [string], (mandatory)
amount: The amount of NEAR which will be delegated [number], (mandatory).
\nvalidator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (madatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of funds from the Twinstake validtaor. This must be followed by the /withdraw transaction.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
delegator_public_key: The public key associated with the delegator address e.g [CQLP1....JYhzfT], [string], (mandatory)
amount: The amount of NEAR which will be undelegated [number], (mandatory).
\nvalidator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned withdraw transaction that can be broadcast to effect the withdrawal of undelegated funds back to the delegator address. Funds must first be undelegated through the /undelegate endpoint.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
delegator_public_key: The public key associated with the delegator address e.g [CQLP1....JYhzfT], [string], (mandatory)
amount: The amount of NEAR which will be withdrawn [number], (mandatory).
\nvalidator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to broadcast a transaction to the Near blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nResponse Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"e5f688e1-123e-4aaa-b8b6-70c73cd75217","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/NEAR/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","NEAR","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"81e3fae7-9407-465f-a18d-4589373c26e6"}],"id":"798b72e4-e0cc-4f18-b4f2-5f613f967e62","description":"Staking and Reporting endpoints for NEAR on the Near blockchain
\n","_postman_id":"798b72e4-e0cc-4f18-b4f2-5f613f967e62","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Osmosis","item":[{"name":"Validator address","id":"b616cbb2-3f57-4200-8532-eb82c1026ccb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/OSMO/validators","description":"This endpoint provides the mainnet Twinstake Osmosis validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"42086cb8-e536-4327-a377-a5db9bec6577","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/OSMO/validators","host":[""],"path":["v2","staking","OSMO","validators"],"query":[{"key":"asset","value":"OSMO","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"osmoval...kqapgq6p\",\n}"}],"_postman_id":"b616cbb2-3f57-4200-8532-eb82c1026ccb"},{"name":"Rewards","id":"93a2b8b6-5f77-4f3f-8754-14b96a95cf7f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/osmosis/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Osmosis address that funds were delegated from
where validator is the Twinstake Osmosis validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Osmosis address that funds were delegated from
where validator is the Osmosis validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in OSMO that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Osmosis for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Osmosis address that funds were delegated from
where validator is the Twinstake Osmosis validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/osmosis/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/osmosis/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/osmosis/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation of assets to a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (mandatory). There is no minimum delegation amount on Osmosis.
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (optional). N.B this is required for an address with no transaction history.
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to claim the rewards from the Twinstake validator, for a given delegator address.
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
delegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to create an unsigned undelegation transaction that can be broadcast to effect the undelegation of assets from a Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (mandatory)
delegator_address: The crypto address which is/will delegated funds to a Twinstake validator e.g \"0x123....xyz\" , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount to delegate, [number], (optional)
\nunstake_all: This allows the full amount to be undelegated without this being specifided, [boolean], (optional)
\ndelegator_address_pubkey: The public key for the associated delegator address, [string], (mandatory)
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format,
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction.
where hex is the unsigned transaction in hexadecimal-encoded format.
This endpoint is to broadcast a transaction to the Osmosis blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nsigned_transaction: The signed version of the transaction, [string], (optional)
\nunsigned_transaction: The unsigned version of the transaction as represented in the hex format within the response of the /delegate endpoint , [string], (optional)
\nsignatures: A list of signatures applied to the unsigned transaction, [string] (optional)
\nN.B one of signed_transaction or (unsigned_transaction & signatures) is required
Response Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where status is \"broadcasted\" when the transaction has been successfully broadcast on the chain or \"failed\" if this has been unable to successfully broadcast on chain.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"1f98bc0c-8d95-4d8a-b9e1-acdaf47514c3","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/OSMO/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","OSMO","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"03f056ad-16a0-43f2-a68b-4b4a2fc1c150"}],"id":"d2823007-2031-46ef-a855-bd16c3fc3500","description":"Staking and Reporting endpoints for OSMO on the Osmosis blockchain
\n","_postman_id":"d2823007-2031-46ef-a855-bd16c3fc3500","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Polygon","item":[{"name":"Validator address","id":"4a8226d6-768c-46d7-9e95-f5e10f3f650a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/POL/validators","description":"This endpoint provides the mainnet Twinstake Polygon validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"ba4e63f1-2cbc-4b48-a3ca-d0bc91e4b137","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/POL/validators","host":[""],"path":["v2","staking","POL","validators"],"query":[{"key":"asset","value":"POL","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"0xeA0...F84712\",\n}"}],"_postman_id":"4a8226d6-768c-46d7-9e95-f5e10f3f650a"},{"name":"Rewards","id":"7d02b461-9d1c-44b2-adaa-56218e2478d7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/polygon/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Polygon address that funds were delegated from
where validator is the Twinstake Polygon validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Polygon address that funds were delegated from
where validator is the Polygon validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in MATIC that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Polygon for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Polygon address that funds were delegated from
where validator is the Twinstake Polygon validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/polygon/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/polygon/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/polygon/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned allowance transaction that can be broadcast on the Ethereum blockchain to authorize the Polygon staking contract to access POL assets for staking. This is part 1 of a 2 stage process and the /delegate transaction must be called next to effect the staking activity.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount of POL which will be delegated [number], (mandatory).
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned delegation transaction that can be broadcast on the Polygon blockchain to stake the approved POL tokens. This is part 2 of a 2 stage process and the /allowance transaction must be called first to ensure the POL tokens are ringfenced for staking on the Ethereum blockchain.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
amount: The amount of POL which will be delegated [number], (mandatory).
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned unbond transaction that can be broadcast to start the unstaking process of POL tokens from the Twinstake validator to the delegator's account. This is part 1 of a 2 stage process and the /unbond_claim endpoint mut be called next to complete the unstaking activity.
\nThis transaction must be broadcast on the Ethereum blockchain.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be undelegated from e.g [0x123...xyz], [string] (mandatory)
amount: The amount of POL which will be undelegated [number], (mandatory).
\nResponse Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned unbond claim transaction that can be broadcast to complete the unstaking process of POL tokens from the Twinstake validator to the delegator's account. This is part 2 of a 2 stage process and the /unbond endpoint mut be called first to initiate the unstaking process.
\nThis transaction must be broadcast on the Ethereum blockchain.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds will be undelegated from e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned reward claim transaction to redeem the accumulated staking rewards for the delegator account.
\nThis transaction must be broadcast on the Ethereum blockchain.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
validator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to broadcast a transaction to the Aptos blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nResponse Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"71fe87bb-77e2-4d50-aad7-20a99aae7c2c","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/POL/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","POL","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"c120e046-d2f5-466e-991b-03ad3ef55cc5"}],"id":"1f909d00-2ec3-4c8c-9d3d-9a9c3a5eb1bb","description":"Staking and Reporting endpoints for POL on the Polygon blockchain
\n","_postman_id":"1f909d00-2ec3-4c8c-9d3d-9a9c3a5eb1bb","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Solana","item":[{"name":"Reporting","item":[{"name":"Validator address","id":"6ee69797-a431-4bc9-98fe-2717da7dc766","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/SOL/validators","description":"This endpoint provides the mainnet Twinstake Solana validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"6176ae7b-d42f-4051-9022-caaa3ce2abca","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/SOL/validators","host":[""],"path":["v2","staking","SOL","validators"],"query":[{"key":"asset","value":"SOL","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"address\": \"Ak5BJ...rfiqR\",\n}"}],"_postman_id":"6ee69797-a431-4bc9-98fe-2717da7dc766"},{"name":"Rewards","id":"af17d105-e480-45c5-915e-0654761ecb65","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/solana/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Solana address that funds were delegated from
where validator is the Twinstake Solana validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is a list of rewards:
where inflation is the inflation generated by the protocol
where MEV is the total maximal extractable value from transaction fees
where pending rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the Solana address that funds were delegated from
where validator is the Solana validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in SOL that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on Solana for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the Solana address that funds were delegated from
where validator is the Twinstake Solana validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/solana/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
where jito_pending_distribution is whether the Solana JITO rewards are awaiting the epoch to end in order to be paid out.
where staking_rewards are the protocol rewards.
where jito_rewards are the JITO specific rewards.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/solana/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits on the given day.
where pending_delegation / pending_activation is any amount which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount of assets withdrawn during the given day.
where pending_exit is the amount which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/solana/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
This endpoint is to create an unsigned create stake account transaction that can be broadcast to effect the creation of a stake account that funds can be delegated to Twinstake from.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
stake_authority_address: A cryptocurrency address on Solana that is used to sign staking related transactions e.g [HN7c...YWrH], [string], (mandatory)
withdraw_authority_address: A cryptocurrency address on Solana that is used to sign withdrawal related transactions e.g [8PjJ...Sjkq], [string], (mandatory)
amount: The amount of SOL which will fund the stake account and be delegated [number], (mandatory).
\nvalidator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (madatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
In addition the following is provided in the response:
\nstake_account_address is the new Solana stake account that will be created from the transactionThis endpoint is to create an unsigned delegation transaction that can be broadcast to effect the delegation from the stake account to the Twinstake validator.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
stake_account_address: A cryptocurrency address on Solana that is used to delegate funds to a validator e.g [HN7c...YWrH], [string], (mandatory)
validator_address: The Twinstake validator address that funds will be delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned split stake transaction that can be broadcast to effect the splitting of stake from a Solana account into two accounts.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
stake_account_address: A cryptocurrency address on Solana that is used to delegate funds to a validator e.g [HN7c...YWrH], [string], (mandatory)
amount: The amount of SOL to split off into the new stake account [number], (mandatory). This must be above 0.01 SOL and the remaining amount in both accounts must be above the rent exempt: https://solana.com/docs/core/fees#rent-exempt
\nvalidator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
In addition the following is provided in the response:
\nnew_stake_account is the new Solana stake account that will be created from the transactionThis endpoint is to create an unsigned merge stake transaction that can be broadcast to effect the merging of stake from two Solana accounts into one account.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
stake_account_source_address: The Solana stake account that funds will be merged in from e.g [HN7c...YWrH], [string], (mandatory)
stake_account_target_address: The Solana stake account that the funds will be merged into e.g [9QgXq...oXDk], [string], (mandatory)
validator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint provides information about the start and end time of the current and next epochs to help optimise any delegation activation timing.
\nRequest Body
\nTo Note:
\nif next_epochs is not provided then the response section for next_epochs returns as default response of empty fields
\nThis endpoint will return mainnet and testnet data
\nResponse Body
\nwhere datetime is the datetime (in UTC) of calculation request
where previous_epoch is the data object containing information about last completed epoch:
where id is the number for the previous epoch
where start_time is the datetime (in UTC) when the last completed epoch started
where end_time is the datetime (in UTC) when the last completed epoch ended
where slot_time is the average time (in milliseconds) of slot for the last completed epoch
where current_epoch is the data object containing information about current epoch:
where id is the number of the current epoch
where start_time is the datetime (in UTC) when the current epoch started
where end_time is the estimated datetime (in UTC) of when the current epoch will end
where transaction_earliest_time is the suggested earliest time (in UTC) to broadcast a delegation for activation in the next epoch. This field is relevant where next_epochs=0
where transaction_latest_timeis the suggested latest time (in UTC) to broadcast a delegation for activation in the next epoch. This field is relevant where next_epochs=0
where next_epochs is the data object containing information about the next unstarted epoch:
\nwhere id is the number of the next epoch
where start_time is the estimated datetime (in UTC) for when the next epoch will start.
where end_time is the estimated datetime (in UTC) for when the next epoch will end.
where transaction_earliest_time is the suggested earliest time (in UTC) to broadcast a delegation in the next epoch for activation in the epoch after that. This field is relevant where next_epochs=1.
where transaction_latest_time is the suggested latest time (in UTC) to broadcast a delegation in the next epoch for activation in the epoch after that This field is relevant where next_epochs=1.
This endpoint is to create an unsigned deactivate transaction that can be broadcast to effect the start of the undelegation process for the funds. After the required cool down period, funds can be withdrawn back to the stake account via the /withdraw endpoint.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
stake_account_address: A cryptocurrency address on Solana that is used to delegate funds to a validator e.g [HN7c...YWrH], [string], (mandatory)
validator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint is to create an unsigned withdraw transaction that can be broadcast to effect the withdrawal of deactivated funds back to the stake account. Funds must first be deactivated through the /deactivate endpoint.
\nFor further information on the delegation and undelegation process please read the protocol's staking guide: https://www.twinstake.io/resources/staking-guides
\nRequest Body
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
delegator_addresses: A crypto addresses which has staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (mandatory)
stake_account_address: A cryptocurrency address on Solana that is used to delegate funds to a validator e.g [HN7c...YWrH], [string], (mandatory)
validator_address: The Twinstake validator address that funds are delegated to e.g [0x123...xyz], [string] (mandatory)
Response Body
\nThe response is an unsigned transaction in three formats, raw, hash and hex.
\nwhere raw is the unsigned transaction in its raw JSON format. This shows the information which had been used to generate the transaction.
where hash is the unsigned transaction as a unique cryptographic identifier for the transaction. This can be used for raw signing processes in MPC wallets.
where hex is the unsigned transaction in hexadecimal-encoded format.This can be used to broadcast the delegation.
This endpoint provides information about the start and end time of the current and next epochs to help optimise any unstaking exit timing.
\nRequest Body
\nTo Note:
\nif next_epochs is not provided then the response section for next_epochs returns as default response of empty fields
\nThis endpoint will return mainnet and testnet data
\nResponse Body
\nwhere datetime is the datetime (in UTC) of calculation request
where previous_epoch is the data object containing information about last completed epoch:
where id is the number for the previous epoch
where start_time is the datetime (in UTC) when the last completed epoch started
where end_time is the datetime (in UTC) when the last completed epoch ended
where slot_time is the average time (in milliseconds) of slot for the last completed epoch
where current_epoch is the data object containing information about current epoch:
where id is the number of the current epoch
where start_time is the datetime (in UTC) when the current epoch started
where end_time is the estimated datetime (in UTC) of when the current epoch will end
where transaction_earliest_time is the suggested earliest time (in UTC) to broadcast a delegation for activation in the next epoch. This field is relevant where next_epochs=0
where transaction_latest_timeis the suggested latest time (in UTC) to broadcast a delegation for activation in the next epoch. This field is relevant where next_epochs=0
where next_epochs is the data object containing information about the next unstarted epoch:
\nwhere id is the number of the next epoch
where start_time is the estimated datetime (in UTC) for when the next epoch will start.
where end_time is the estimated datetime (in UTC) for when the next epoch will end.
where transaction_earliest_time is the suggested earliest time (in UTC) to broadcast a delegation in the next epoch for activation in the epoch after that. This field is relevant where next_epochs=1.
where transaction_latest_time is the suggested latest time (in UTC) to broadcast a delegation in the next epoch for activation in the epoch after that. This field is relevant where next_epochs=1.
This endpoint is to broadcast a transaction to the Solana blockchain. Please note that to be valid, it must be signed by your chosen wallet provider/custodian.
\nRequest Body
\nResponse Body
\nwhere transaction_hash is the uniquely identifiable hash for the transaction. This can be used with any block explorer to see the transaction.
where message is further information about the broadcast success or failure.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation.
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"5b9a1570-acd9-492d-84f2-e67e2dd8fa60","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/SOL/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","SOL","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"fdabcec1-7912-49ca-ba02-84d7210d60f9"}],"id":"98d60601-fd7f-4c64-ac99-bfa8058a78ac","description":"Staking and Reporting endpoints for SOL on the Solana blockchain
\n","_postman_id":"98d60601-fd7f-4c64-ac99-bfa8058a78ac","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Radix","item":[{"name":"Validator address","id":"0ee6ebdf-48a8-48b4-b0cb-c19215b4d1de","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/XRD/validators","description":"This endpoint provides the mainnet Twinstake Radix validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"373eacd0-b15d-4d6f-b93c-55da36f10956","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/XRD/validators","host":[""],"path":["v2","staking","XRD","validators"],"query":[{"key":"asset","value":"XRD","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"address\": \"validator_rdx1...ry94yva\"\n },\n {\n \"address\": \"validator_rdx1s...6csua\"\n }\n]"}],"_postman_id":"0ee6ebdf-48a8-48b4-b0cb-c19215b4d1de"}],"id":"13828d1a-3cb1-4947-975b-adc668616119","_postman_id":"13828d1a-3cb1-4947-975b-adc668616119","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"Starknet","item":[{"name":"Validator address","id":"a912763b-907c-4d8a-a091-3160621ca7c4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/STRK/validators","description":"This endpoint provides the mainnet Twinstake Radix validator address that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"6dbfa5c6-2282-48c2-af40-fa73458855fb","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/STRK/validators","host":[""],"path":["v2","staking","STRK","validators"],"query":[{"key":"asset","value":"STRK","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"address\": \"0x07787...181dc\"\n }\n]"}],"_postman_id":"a912763b-907c-4d8a-a091-3160621ca7c4"}],"id":"7d44f09a-af14-4488-a70d-59e74fc3a1b9","_postman_id":"7d44f09a-af14-4488-a70d-59e74fc3a1b9","description":"","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}},{"name":"The Open Network","item":[{"name":"Validator address","id":"5e592428-080b-4c0b-83f2-48bfa24dd882","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/staking/TON/validators","description":"This endpoint provides the mainnet Twinstake Open Network validator address/es that funds can be delegated to.
\nFor testnet activity, if Twinstake has an active testnet validator, then its address will be provided, otherwise a high performance validator run by the foundation/chain or non-competitor will be provided.
\nQuery Params
\nCustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)Response Body
\naddress is the Twinstake validator address to delegate funds to.The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"}],"variable":[]}},"response":[{"id":"631a5709-7623-4000-98ee-0a6bce540bc8","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/TON/validators","host":[""],"path":["v2","staking","TON","validators"],"query":[{"key":"asset","value":"TON","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"address\": \"EQBnDF...6JjRPm\"\n },\n {\n \"address\": \"EQC1X...g5kR6d6\"\n }\n]"}],"_postman_id":"5e592428-080b-4c0b-83f2-48bfa24dd882"},{"name":"Rewards","id":"368d0676-4da7-4bb5-b381-ec922b232c11","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/v2/reporting/ton/rewards","description":"This endpoint provides information about the rewards related information per asset for a given date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the TON address that funds were delegated from
where validator is the Twinstake TON validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where apr is the annualised percentage rate associated with the validator for the given delegators and entity_filter
where apy is the annualised percentage yield associated with the validator for the given delegators and entity_filter, taking into account any auto-compounding of rewards for the validator
where rewards is the inflation generated by the protocol
where pending_rewards is a list of rewards not distributed to the delegators. This may be not applicable for some chains.
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific date range.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere delegator is the TON address that funds were delegated from
where validator is the TON validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where ACTIVE is the amount in TON that is being staked to the Twinstake validator and actively earning rewards
This endpoint provides transaction information about all depositing or withdrawing activity on TON for Twinstake validator/s.
\nQuery Parameters
\ndate_from: The date that rewards information should be shown from in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
date_to: The date that rewards information should be shown until in the format of YYYY-MM-DD e.g 2025-11-06, [string], (optional)
If date_to and date_from are not provided the previous month of data is defaulted to.
\ndelegators: A single or array of identifiers which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], list[string], (optional)
validators: The Twinstake validator to see staking information about e.g [\"0x123XYZ\"], list[string], [optional]
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
page: The number of pages in the response e.g 2, [integer], (optional)
page_size: The number of delegator/validator pairs in the response e.g 500, [integer], (optional)
These parameters are to ensure the response is performant in the case that a delegator_addresses or entity_filter has a high number of validators associated. If these parameters are not specified then page=1 and page_size=10 will be used.
\nResponse Body
\nwhere id is the transaction identifier
where delegator is the TON address that funds were delegated from
where validator is the Twinstake TON validator address
where entity is the identifier for the custodian.client.hierarchy mapping
where type is whether the transaction is STAKING, UNSTAKING, WITHDRAW or RESTAKE activity
where amount is the transaction amount in the chain’s base unit
where timestamp is the date and time that the transaction was processed onchain (UTC)
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/ton/rewards ]
This endpoint provides information about the rewards related information per asset for a given day.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01 , [string], (optional)
delegator_addresses: A single or an array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz] , [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where address is the delegator address where funds were sent to Twinstake from.
where active_delegation_amount is the total amount being actively staked or delegated for the given day.
where rewards_amount is the total amount, nanoton, of rewards generated for the given day.
where apr is the APR for that given day.
where apy is the APY for the given day.
where epoch_ended_on_day is the last epoch to have ended in the given day, this will be blank if no epoch ended that day.
where epoch/checkpoint_length is the number of days in the epoch/checkpoint/period N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_start is the date and time that the epoch began. N.B this will be an empty field for any days where the epoch continues across multiple days.
where epoch/checkpoint_end is the date and time that the epoch ended. N.B this will be an empty field for any days where the epoch continues across multiple days.
where annual_epochs/checkpoints is the number of epochs in a 365 day period based on the length of the current epoch.
where return_over_epoch/day is the ROI as calculated by daily return over staked amount.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/ton/stakes ]
This endpoint provides information about the latest staked position or a snapshot of the staked position for a specific day. It can show information at an asset level or for specific delegator addresses or entity filter.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
delegator_addresses: A single or array of crypto addresses which have staked or delegated funds to a Twinstake validator e.g [0x123....xyz], [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ, [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset , delegator_addresses and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where active_delegation_amount / active_stake_amount is the total amount in nanoton being actively staked or delegated for the given day.
where active_validator_count is the number of Ethereum validators that are active for the given day.
where new_delegations / new_deposits are any new delegations or staking deposits, in nanoton, on the given day.
where pending_delegation / pending_activation is any amount, in nanoton, which is currently warming up/in the activation queue and not yet actively earning rewards by the given day.
where next_delegation_eta / next_activation_eta is the timestamp for when the next staking deposit or delegation warm up will occur. Where there are multiple, this is the earliest.
where exited_delegation / exited_stake is the amount, in nanoton, of assets withdrawn during the given day.
where pending_exit is the amount, in nanoton, which is within the withdrawal or cool down period but which is not yet accessible or fully exited.
where next_exit_eta is the timestamp for when the next staking withdrawal or delegation cool down will occur. Where there are multiple, this is the earliest.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026. PLEASE MIGRATE TO /v2/reporting/ton/transactions ]
This endpoint provides transaction information about all depositing or withdrawing activity on Ethereum and all delegating and undelegating activity on the blockchains which Twinstake supports.
\nRequest Body
\nasset: The ticker of a crypto asset e.g SOL , [string], (optional)
from_date: In the format of YYYY-MM-DD e.g 2023-10-01, [string], (optional)
entity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
To Note
\nIf date is not provided then the response will be for the last completed 24h period
asset and entity_filter are optional parameters
Response Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash for the delegation/staking/undelegation/unstaking activity.
where amount is the amount staked/delegated (or unstaked/undelegated) in the native asset.
where type is the transaction type e.g STAKE, REWARD, UNSTAKE, WITHDRAW REWARDS etc.
where datetime is the time of the transaction (or first in a batch of transactions) in the format of YYYY-MM-DD HH:MM:SS.
where stake_account is the delegator address where funds were sent to Twinstake from.
where explorer_url is a link to the transaction information with a relevant block explorer.
[THIS ENDPOINT WILL BE DEPRECATED ON 29th JANUARY 2026]
\nThis endpoint is to provide users with information about the status of an asset delegation or undelegation
\nPath Parameter
\nATOM , [string], (mandatory)Query Parameters
\nentity_filter: The identifier of the custodian or client in the format of Custodian.Client.Hierarchy e.g CustodianA.ClientB or CustodianX.ClientY.HierarchyZ , [string], (optional)
transaction_hash: The transaction of the delegation or undelegation activity e.g CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR , [strong], (optional)
Where either of transaction_hash or entity_filter must be provided
\nResponse Body
\nwhere entity is the identifier for the custodian.client.hierarchy mapping.
where transaction_hash is the transaction hash where the user has delegated or undelegated the asset.
where amount is the amount delegated (or undelegated) in the native asset amount.
where delegator_address is the address that has delegated funds to Twinstake.
where status is any of:
delegation_pending: where the delegation transaction has been broadcast, processed but not yet through the required bonding/warm up period
\ndelegated: the delegated transaction is through the necessary warm up period and the funds are actively delegated to the validator and earning rewards
\nundelegation_pending: where the undelegation transaction has been broadcast, processed but not yet through the required unbonding/cool down period
\nundelegated: the undelegated transaction is through the necessary cool down period and the funds are actively undelegated from the validator and no longer earning rewards but where they have not yet been received back to the user's account
\nwithdrawn: the funds are undelegated and have now been withdrawn back to the user's account
\nwhere eta_until is the time (format HH:MM:SS) until:
the delegation is actively earning rewards (where the status is related to a delegation being made to us but still within the bonding period)
\nthe delegation is completely withdrawn from our validator (where the status is related to an undelegation but still within the unbonding period)
\nThe identifier of the custodian or client in the format of Custodian.Client.Hierarchy
\n","type":"text/plain"},"key":"entity_filter","value":"CustodianA.ClientB"},{"disabled":true,"description":{"content":"The transaction of the delegation or undelegation activity
\n","type":"text/plain"},"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"}],"variable":[]}},"response":[{"id":"425cc3ef-3566-4f61-a662-a6facdb28273","name":"Successful response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"/v2/staking/TON/status?transaction_hash=CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR&entity_filter=Custodian.Client.Hierarchy","host":[""],"path":["v2","staking","TON","status"],"query":[{"key":"transaction_hash","value":"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR"},{"key":"entity_filter","value":"Custodian.Client.Hierarchy","type":"text"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n\t{\n\t\t\"entity\": \"Custodian.Client.Hierarchy\",\n\t\t\"delegator_address\": \"32fdh7fnsus89ydfnu92z8y4h47x\",\n\t\t\"date\": \"2023-01-30\",\n\t\t\"amount\": \"1500345\"\n\t\t\"transaction_hash\": \"CRLBe5sMbDn5nEnmW46PxvymbbLtsFrNeUuZCEtKaYfR\"\n\t\t\"status\": \"undelegation_pending\"\n\t\t\"eta_until\": \"00:24:13\"\n\t},\n]"}],"_postman_id":"77a85fa6-3add-4a22-b26a-a28cdabdd563"}],"id":"a075b828-89cf-46d4-9981-a28c3652ca91","description":"Staking and Reporting endpoints for TON on the Open Network blockchain
\n","_postman_id":"a075b828-89cf-46d4-9981-a28c3652ca91","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":true,"source":{"_postman_id":"f832e69c-1967-4832-a03d-d2d7293550fc","id":"f832e69c-1967-4832-a03d-d2d7293550fc","name":"Twinstake API V2 Documentation","type":"collection"}}}],"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"17b61667-8b67-4987-9696-772aaac57171","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"435c0fef-46e3-4681-a1c8-e0a4698cbb12","type":"text/javascript","exec":[""]}}],"variable":[{"key":"baseUrl","value":"","type":"default"},{"key":"token","value":"","type":"string"}]}