Endpoints

API Usage

Once you have access to the Staking API with a validated user and existing API keys, you can start using this service.

Try it live

tip

Every endpoint on this page can be executed from the interactive Swagger console, using your own X-API-KEY.

The machine-readable OpenAPI schema is available at:

Staking OpenAPI schema

Authentication

In order to use the Staking API endpoints you need to include your API KEY.

tip

Heads up! To obtain a valid API key required for authentication, please refer to the Authentication > Create API keys section of the documentation.

Header:

Name	Description	Example value	Required
`X-API-KEY`	Your api key value	`<API_KEY_VALUE>`	✅
`X-NETWORK`	Blockchain network identifier	`1672`	⚪
`X-IDENTITY`	Caller-defined identity stored in the audit log	`user-1234`	⚪

X-NETWORK header

Use the X-NETWORK header to select the Pharos network. Faroo is available on Pharos mainnet (1672).

info

If you omit the header, the API uses the default Faroo network of your account. When Faroo is not configured for the requested network, the API returns 503.

X-IDENTITY header

Use the X-IDENTITY header to attribute a request to the end user or account that acts through your integration. The value is caller-defined. The API stores it with the request in the audit log.

info

The header is optional and does not change the response. Use an opaque internal identifier, such as a user ID or an account reference. Do not send personal data such as emails or names. If you omit the header, the API attributes the request only to your API key.

Amounts and units

All amounts are JSON numbers in PROS (ether units), with a maximum of 18 decimals. Do not send wei. The API converts the amounts of undelegate to stPROS shares at the current exchange rate.

List available networks

Use this helper endpoint to get the list of Faroo networks that are enabled for your API key.

Endpoint: /api/v1/pharos/faroo/networks

Response payload fields:

Field	Type	Required	Description
`name`	string	✅	Blockchain name
`type`	string	✅	Blockchain type
`chain_id`	string	✅	Chain identifier
`is_default`	boolean	✅	Whether this is the default network for this controller

Example

curl "https://staking-api.stakely.io/api/v1/pharos/faroo/networks" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672"

Response:

[
  {
    "name": "pharos-faroo",
    "type": "EVM",
    "chain_id": "1672",
    "is_default": true
  }
]

Staking information

Get the staking parameters of this protocol:

Endpoint: /api/v1/pharos/faroo/staking-info

Description

Staking parameters for Faroo on Pharos: activation, deactivation and withdrawal times in minutes, fees, current APR/APY, slashing risk and stake limits. The API serves them from an in-memory snapshot that it refreshes hourly.

staking_apr and staking_apy are null until the rewards feed publishes them.
stake_deactivation_max_time is null, because the real wait depends on the liquidity of the vault.
staking_reward_fee and withdrawal_fee are null, because the protocol does not publish its fees on chain.

Returned

Field	Type	Required	Description
`stake_activation_max_time`	number	✅	Maximum time, in minutes, for a new stake to become active and start accruing rewards. `0` means it is effective immediately.
`stake_deactivation_max_time`	number	✅	Maximum time, in minutes, for an unstake request to complete the unbonding/exit period. `0` means the stake is released immediately.
`withdrawal_max_time`	number	✅	Maximum time, in minutes, between a completed deactivation and the funds being spendable again. `0` means the funds are available as soon as the deactivation completes.
`staking_reward_fee`	number	✅	Aggregate fee charged on staking rewards, as a percentage of the rewards generated (validator commission plus any protocol fee).
`withdrawal_fee`	number	✅	Fee charged when withdrawing the stake, as a percentage of the withdrawn amount. Network transaction (gas) costs are not included.
`staking_apr`	number	✅	Current annual percentage rate (rewards without compounding), as a percentage.
`staking_apy`	number	✅	Current annual percentage yield (rewards with compounding), as a percentage.
`max_slashing_percentage`	number	✅	Maximum percentage of the staked amount that the protocol can slash. `0` means the protocol implements no slashing.
`min_stake_amount`	string	✅	Minimum amount that can be staked, as a decimal string in the native token of the chain.
`max_stake_amount`	string	✅	Maximum amount that can be staked, as a decimal string in the native token of the chain. `null` means the protocol enforces no upper limit.
`users`	number	✅	Number of addresses currently staking with Stakely on this chain. Live figure, refreshed hourly. `null` on protocol-scoped endpoints (liquid staking, vaults), because the feed only publishes this per chain and the chain-wide figure is not that protocol's.
`tvl_usd`	number	✅	Total value staked with Stakely on this chain, in USD. Live figure, refreshed hourly. `null` on protocol-scoped endpoints, for the same reason as `users`.
`tvl_token`	number	✅	Total value staked with Stakely on this chain, in the native token of the chain. Live figure, refreshed hourly. `null` on protocol-scoped endpoints, for the same reason as `users`.

Example

curl "https://staking-api.stakely.io/api/v1/pharos/faroo/staking-info" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672"

Response:

{
  "stake_activation_max_time": 0,
  "stake_deactivation_max_time": null,
  "withdrawal_max_time": 0,
  "staking_reward_fee": null,
  "withdrawal_fee": null,
  "staking_apr": null,
  "staking_apy": null,
  "max_slashing_percentage": null,
  "min_stake_amount": null,
  "max_stake_amount": null,
  "users": null,
  "tvl_usd": null,
  "tvl_token": null
}

Delegate action

Craft a Faroo delegate transaction:

Endpoint: /api/v1/pharos/faroo/action/delegate

Description

This endpoint crafts a transaction that calls depositWithPROS() on the Faroo vault. The transaction sends amount as its value, and the vault mints stPROS in the same transaction. You do not need an approve transaction.

The API returns 400 when the amount is 0, when the balance of address does not cover the amount and the network fee, or when the amount is more than the deposit limit of the vault.

Request body parameters

Field	Type	Required	Description
`address`	string	✅	Address that will stake PROS and receive stPROS
`amount`	number	✅	Amount of PROS to stake, sent as the transaction value

Returned

Field	Type	Required	Description
`serialized_tx_hex`	string	✅	Serialized transaction hex string ready to be signed
`unsigned_tx_hash_hex`	string	✅	Unsigned tx hash hex string used for offline signing integrations
`payload`	object	✅	Transaction payload object

Example

curl -X POST "https://staking-api.stakely.io/api/v1/pharos/faroo/action/delegate" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "0xb794f5ea0ba39494ce839613fffba74279579268",
  "amount": 1
}'

Response:

{
  "serialized_tx_hex": "e9830123458402faf08083030d40946b0a44c64190279f7034b77c13a566e914fe5ec4880de0b6b3a764000084...",
  "unsigned_tx_hash_hex": "0x1a6edb7358323bafca52b1755f3ad985754dc23887110b65429373ed83321500",
  "payload": {
    "type": "0x0",
    "nonce": "0x12345",
    "gasLimit": "0x30d40",
    "to": "0x6b0a44c64190279f7034b77c13a566e914fe5ec4",
    "value": "0xde0b6b3a7640000",
    "data": "0x...",
    "gasPrice": "0x2faf080"
  }
}

Undelegate action

Craft a Faroo undelegate transaction:

Endpoint: /api/v1/pharos/faroo/action/undelegate

Description

This endpoint crafts a transaction that calls redeem(shares, address, address) on the Faroo vault. The API converts amount from PROS to stPROS shares. The transaction adds an entry to the withdrawal queue of address.

To exit in full, send staked_amount from the staking balance endpoint without a change. The API then redeems all of the stPROS of the address.

The API returns 400 when the amount is more than the staked balance, when the amount converts to zero stPROS, or when the withdrawal queue of the address is full. Each address can have a maximum of 5 entries. Withdraw the claimable entries first, then try again.

Request body parameters

Field	Type	Required	Description
`address`	string	✅	Address that holds the stPROS and will unstake
`amount`	number	✅	Amount of PROS (vault assets) to unstake; converted to stPROS shares. Send `staked_amount` from staking-balance, unchanged, to exit in full.

Returned

Field	Type	Required	Description
`serialized_tx_hex`	string	✅	Serialized transaction hex string ready to be signed
`unsigned_tx_hash_hex`	string	✅	Unsigned tx hash hex string used for offline signing integrations
`payload`	object	✅	Transaction payload object

Example

curl -X POST "https://staking-api.stakely.io/api/v1/pharos/faroo/action/undelegate" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "0xb794f5ea0ba39494ce839613fffba74279579268",
  "amount": 0.5
}'

The response has the same shape as the delegate action.

Withdraw action

Craft a Faroo withdraw transaction:

Endpoint: /api/v1/pharos/faroo/action/withdraw

Description

This endpoint crafts a transaction that calls withdrawCompleteToPROS() on the Faroo vault. One transaction pays out every claimable entry of the withdrawal queue of address. The action has no request identifier.

Call this endpoint when stake_withdrawing_amount in the staking balance endpoint is greater than 0. The API returns 400 when the address has no claimable entry.

Request body parameters

Field	Type	Required	Description
`address`	string	✅	Address that claims its matured withdrawals. Every claimable queue entry is paid out in one transaction

Returned

Field	Type	Required	Description
`serialized_tx_hex`	string	✅	Serialized transaction hex string ready to be signed
`unsigned_tx_hash_hex`	string	✅	Unsigned tx hash hex string used for offline signing integrations
`payload`	object	✅	Transaction payload object

Example

curl -X POST "https://staking-api.stakely.io/api/v1/pharos/faroo/action/withdraw" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "0xb794f5ea0ba39494ce839613fffba74279579268"
}'

The response has the same shape as the delegate action.

Prepare action

Join the signature and the unsigned transaction:

Endpoint: /api/v1/pharos/faroo/action/prepare

Description

This endpoint joins the unsigned transaction and the parts of the signature (r, s, v) into one signed transaction.

r and s are hex strings, with or without the 0x prefix.
v can be the recovery id (0 or 1), 27 or 28, or the EIP-155 value (chain_id * 2 + 35 + recovery). The API converts it to the EIP-155 value. Any other value returns 400.

Request body parameters

Field	Type	Required	Description
`serialized_tx_hex`	string	✅	Unsigned serialized transaction hex string ready to be signed
`r`	string	✅	`r` part of the ECDSA signature: up to 32 bytes of hex, with or without the `0x` prefix.
`s`	string	✅	`s` part of the ECDSA signature: up to 32 bytes of hex, with or without the `0x` prefix.
`v`	number	✅	`v` part of the ECDSA signature: the recovery id (`0` or `1`), `27` or `28`, or the EIP-155 value `chain_id * 2 + 35 + recovery`. The API converts it to the EIP-155 value.

Returned

Field	Type	Required	Description
`signed_tx_hex`	string	✅	Signed transaction hex string ready to be broadcasted

Example

curl -X POST "https://staking-api.stakely.io/api/v1/pharos/faroo/action/prepare" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672" \
  -H "Content-Type: application/json" \
  -d '{
  "serialized_tx_hex": "e9830123458402faf08083030d40946b0a44c64190279f7034b77c13a566e914fe5ec4880de0b6b3a764000084...",
  "r": "6da2b6fe309b629720bc3d1d3a8befb3f461e3b53ccee85c55d10b11d3a3d263",
  "s": "085fe4bb8ff0c04e4e41a2ba44609f894b9a70f4330de726d1403ee21b65e685",
  "v": 3379
}'

Response:

{
  "signed_tx_hex": "0xf8698301234584..."
}

Broadcast action

Broadcast a signed transaction:

Endpoint: /api/v1/pharos/faroo/action/broadcast

Description

Broadcast a signed Faroo transaction.

Request body parameters

Field	Type	Required	Description
`signed_tx_hex`	string	✅	Signed transaction hex string ready to be broadcasted

Returned

Field	Type	Required	Description
`tx_hash`	string	✅	Transaction hash of the broadcasted transaction

Example

curl -X POST "https://staking-api.stakely.io/api/v1/pharos/faroo/action/broadcast" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672" \
  -H "Content-Type: application/json" \
  -d '{
  "signed_tx_hex": "0xf8698301234584..."
}'

Response:

{
  "tx_hash": "0x23273dacef9d64fdb2c790e9f9f4c13574125078a272059dac2473bc8bfba163"
}

Unified staking balance

Get the staking balance for the given address in the unified cross-protocol shape:

Endpoint: /api/v1/pharos/faroo/staking-balance/{address}

Description

Staking balance for an address in the unified cross-protocol shape, in PROS. The vault mints stPROS on deposit, and rewards accrue through the exchange rate. Thus stake_activation_amount and stake_rewards_amount are null.

staked_amount is the PROS value of the stPROS of the address. Send it without a change to the undelegate action to exit in full.
stake_withdrawing_amount is the PROS that the withdraw action can pay out now.
stake_deactivation_amount is the rest of the withdrawal queue.

Each entry of the withdrawal queue is a staking object of type withdrawal_request. Its id is the 0-based position of the entry in the queue. The id is for information only: the withdraw action pays out every claimable entry, and the positions change after a withdrawal. An entry that the vault paid in part stays deactivating, and its claimable part is already in stake_withdrawing_amount. withdrawable_at is the earliest estimate, because the queue also waits for liquidity.

The API returns 400 when address is not a valid address.

Request parameters

Parameter	In	Type	Required	Description
`address`	path	string	✅	Address to query the Faroo position for

Returned

Field	Type	Required	Description
`staked_amount`	number	✅	Stake that is currently active and earning rewards, in native token units.
`stake_activation_amount`	number	✅	Stake that has been delegated but is still warming up, in native token units. `null` when the protocol activates stake immediately.
`stake_deactivation_amount`	number	✅	Stake that is unbonding and has not completed its deactivation period yet, in native token units. `null` when the protocol has no unbonding period.
`stake_withdrawing_amount`	number	✅	Stake that finished deactivating and is waiting for a withdrawal transaction, in native token units. `null` when the protocol releases the funds automatically.
`stake_rewards_amount`	number	✅	Rewards that can be claimed, in native token units. `null` when the protocol compounds rewards into `staked_amount` instead of accruing them separately.
`staking_objects`	StakingObjectDto[]	✅	Individually addressable units that make up the position, normalised across protocols. The amounts above are the aggregate; these are the handles needed to act on the position, because protocols such as Solana and Sui require an object id to craft an unstake or withdraw transaction. `null` means the protocol exposes no addressable objects at all and every action is amount-based; an empty array means it does expose them and the address currently holds none. An object is only listed when the protocol publishes a real identifier for it, so the listed objects do not necessarily add up to the totals above.

Each item in staking_objects is a StakingObjectDto:

Field	Type	Required	Description
`id`	string	✅	Identifier of this object on its protocol, passed back to the action endpoints of that protocol (see below).
`type`	StakingObjectType	✅	Whether the object holds stake (`delegation`) or represents an exit already requested (`withdrawal_request`).
`status`	StakingObjectStatus	✅	Lifecycle phase of the object. Objects sharing a status add up to the matching amount bucket of the response.
`amount`	number	✅	Principal held by this object, in native token units. `null` when it could not be read.
`rewards_amount`	number	✅	Rewards accrued by this object on top of its principal, in native token units. `null` when the protocol reports rewards only at address level, compounds them into the principal, or when they could not be derived.
`validator_address`	string	✅	Validator this object is delegated to, in the protocol native format (a vote account on Solana, a validator address on Sui). `null` when the protocol does not attribute the object to a single validator.
`activation_epoch`	number	✅	Epoch at which this object starts earning rewards. `null` on protocols that do not track activation per object.
`withdrawable_epoch`	number	✅	Epoch from which this object can be withdrawn. `null` on protocols whose withdrawal is time-based or that release funds automatically.
`withdrawable_at`	string	✅	ISO-8601 instant from which this object can be withdrawn. `null` on protocols whose withdrawal is epoch-based or that release funds automatically.

On Faroo the id is the 0-based position of the entry in the withdrawal queue. It is for information only. The withdraw action takes no identifier.

type values:

Value	Description
`delegation`	The object holds stake.
`withdrawal_request`	The object represents an exit that has already been requested.

status values:

Value	Description
`activating`	Warming up, not earning rewards yet. Adds up to `stake_activation_amount`.
`active`	Live and earning rewards. Adds up to `staked_amount`.
`deactivating`	Unbonding, deactivation period not finished. Adds up to `stake_deactivation_amount`.
`withdrawable`	Deactivated and waiting for a withdrawal transaction. Adds up to `stake_withdrawing_amount`.
`unknown`	The lifecycle phase could not be derived from the protocol data.

Example

curl "https://staking-api.stakely.io/api/v1/pharos/faroo/staking-balance/0xb794f5ea0ba39494ce839613fffba74279579268" \
  -H "X-API-KEY: $STAKELY_API_KEY" \
  -H "X-NETWORK: 1672"

Response:

{
  "staked_amount": 0,
  "stake_activation_amount": null,
  "stake_deactivation_amount": 1.0328574356664164,
  "stake_withdrawing_amount": 0,
  "stake_rewards_amount": null,
  "staking_objects": [
    {
      "id": "0",
      "type": "withdrawal_request",
      "status": "deactivating",
      "amount": 1.0328574356664164,
      "rewards_amount": null,
      "validator_address": null,
      "activation_epoch": null,
      "withdrawable_epoch": null,
      "withdrawable_at": "2026-10-27T06:47:24.000Z"
    }
  ]
}

This position was observed on Pharos mainnet. The address has one entry in the withdrawal queue, and the entry still waits for liquidity.

Errors

The action endpoints and the staking balance endpoint of this protocol return errors in this shape:

{
  "status": 400,
  "errors": {
    "message": "No claimable withdrawals"
  }
}

Field	Description
`status`	HTTP status code.
`errors.message`	Description of the problem. When the simulation of a transaction fails, it contains the revert reason of the contract.

The API simulates each transaction on chain before it returns it. If the simulation fails, the API returns 422 and no transaction. This prevents a transaction that reverts and costs gas.

Status	Cause
`400`	The request is not valid for the current position: the amount is `0` or above the balance, the amount is above the deposit limit of the vault, the withdrawal queue is full, there is no claimable entry to withdraw, or `address` is not a valid address.
`422`	The vault is paused, or the simulation of the transaction fails.
`503`	Faroo is not configured for the requested network.

401 when the X-API-KEY header is missing or not valid uses the common error format.

API Usage​

Try it live​

Authentication​

X-NETWORK header​

X-IDENTITY header​

Amounts and units​

List available networks​

Example​

Staking information​

Description​

Returned​

Example​

Delegate action​

Description​

Request body parameters​

Returned​

Example​

Undelegate action​

Description​

Request body parameters​

Returned​

Example​

Withdraw action​

Description​

Request body parameters​

Returned​

Example​

Prepare action​

Description​

Request body parameters​

Returned​

Example​

Broadcast action​

Description​

Request body parameters​

Returned​

Example​

Unified staking balance​

Description​

Request parameters​

Returned​

Example​

Errors​

API Usage

Try it live

Authentication

X-NETWORK header

X-IDENTITY header

Amounts and units

List available networks

Example

Staking information

Description

Returned

Example

Delegate action

Description

Request body parameters

Returned

Example

Undelegate action

Description

Request body parameters

Returned

Example

Withdraw action

Description

Request body parameters

Returned

Example

Prepare action

Description

Request body parameters

Returned

Example

Broadcast action

Description

Request body parameters

Returned

Example

Unified staking balance

Description

Request parameters

Returned

Example

Errors