Skip to main content
Delegated staking allows DAG holders to delegate their token locks to validator nodes in exchange for staking rewards. The delegated stake system is built on top of token locks — you must first create a TokenLock (via the DAG L1 API) before creating a delegated stake.
All endpoints return the following response headers:
  • X-Id — The node’s public key identifier
  • X-Session-Token — The current cluster session token
  • Request-Signature — Cryptographic signature of the response for verification
Prerequisites: Before creating a delegated stake, you must:
  1. Create a TokenLock via the DAG L1 /token-locks endpoint with unlockEpoch: null (indefinite lock)
  2. Note the returned hash — this becomes the tokenLockRef in your delegated stake request

​
POST /delegated-stakes

Creates a new delegated stake or updates an existing one.
  • Create: Provide a tokenLockRef pointing to a TokenLock with a null unlockEpoch value.
  • Update (re-delegate): Provide the same tokenLockRef as the original stake with a new nodeId. The lock and all accrued rewards are transferred to the new node without waiting for the unlock period.
curl -X POST https://<node-host>:9000/delegated-stakes \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "source": "DAG3hZTBgtb2iH9ZdLNvaKqPT4ZncCuW6uYxZack",
      "nodeId": "c7f9a08bdea7ff5f51c8af16e223a1d751bac9c541125d9aef5658e9b7597aee",
      "amount": 2567890,
      "fee": 256,
      "tokenLockRef": "abc123...",
      "parent": { "ordinal": 0, "hash": "" }
    },
    "proofs": [
      { "id": "<public-key-hex>", "signature": "<ecdsa-der-hex>" }
    ]
  }'
Request body — SignedCreateDelegatedStake
​
value
object
required
The delegated stake creation payload
​
proofs
array
required
Array of cryptographic signature proofs from the source address owner
Response 200 OK
​
hash
string
Hash of the accepted delegated stake create transaction
Response 400 Bad Request
​
errors
array
Array of error cause objects
Response 503 Service Unavailable Node is not in Ready state.

​
PUT /delegated-stakes

Withdraws an existing delegated stake. After withdrawal, the locked tokens and all available rewards are released after the unlock period has elapsed. 
curl -X PUT https://<node-host>:9000/delegated-stakes \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "source": "DAG3hZTBgtb2iH9ZdLNvaKqPT4ZncCuW6uYxZack",
      "tokenLockRef": "abc123...",
      "parent": { "ordinal": 1, "hash": "abc123..." }
    },
    "proofs": [
      { "id": "<public-key-hex>", "signature": "<ecdsa-der-hex>" }
    ]
  }'
Request body — SignedWithdrawDelegatedStake Same envelope structure as POST /delegated-stakes but with a WithdrawDelegatedStake value payload containing source, tokenLockRef, and parent. Response 200 OK
​
hash
string
Hash of the accepted delegated stake withdrawal transaction
Response 400 Bad Request Invalid withdrawal request. Returns an ErrorResponse with rejection reasons. Response 503 Service Unavailable Node is not in Ready state.

​
GET /delegated-stakes//info

Returns all delegated stake positions (active and pending withdrawal) for a given address. 
curl https://<node-host>:9000/delegated-stakes/DAG3hZTBgtb2iH9ZdLNvaKqPT4ZncCuW6uYxZack/info
​
address
string
required
DAG wallet address to query
Response 200 OK
​
address
string
The queried wallet address
​
activeDelegatedStakes
array
Currently active delegated stake positions
​
pendingWithdrawals
array
Stakes in the withdrawal pending state (same schema as activeDelegatedStakes)

​
GET /delegated-stakes/last-reference/

Returns the last delegated stake transaction reference for a given address. Use this to build the parent field for new delegated stake requests. 
curl https://<node-host>:9000/delegated-stakes/last-reference/DAG3hZTBgtb2iH9ZdLNvaKqPT4ZncCuW6uYxZack
​
address
string
required
DAG wallet address
Response 200 OK
​
ordinal
integer
Ordinal of the last delegated stake transaction (0 if none)
​
hash
string
Hash of the last delegated stake transaction (empty string if none)
Example response: 
{
  "ordinal": 3,
  "hash": "a1b2c3d4e5f6..."
}
Response 503 Service Unavailable Node is not in Ready state.

​
GET /delegated-stakes/rewards-info

Returns global rewards configuration and statistics. Use this data to calculate estimated APY for delegated staking positions. 
curl https://<node-host>:9000/delegated-stakes/rewards-info
Response 200 OK
​
epochsPerYear
integer
Number of epochs per year, based on current global snapshot epoch configuration
​
currentDagPrice
integer
Current DAG price expressed in datum/USD format
​
nextDagPrice
object
Information about the next DAG price and the epoch at which it takes effect
​
totalDelegatedAmount
integer
Total amount delegated across all active stakes (including accrued rewards), in datums
​
latestAverageRewardPerDag
integer
Average reward rate per DAG per epoch, in datums
​
totalDagAmount
integer
Current total supply of all DAG balances, in datums
​
totalRewardsPerLatestEpoch
integer
Total incremental rewards added in the latest epoch, in datums
​
totalRewardsPerYearEstimate
integer
Estimated total annual reward per DAG in datums (latestAverageRewardPerDag × epochsPerYear)
Response 503 Service Unavailable Node is not in Ready state.

Build docs developers (and LLMs) love

Get started for freeTalk to us