Skip to main content
Node collateral is a mechanism by which node operators lock DAG tokens as a security deposit to participate in consensus. Like delegated stakes, node collateral is backed by a TokenLock created on the DAG L1 layer.
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 posting node collateral, you must create a TokenLock via the DAG L1 /token-locks endpoint. The hash of that token lock transaction is used as tokenLockRef in collateral requests.

​
POST /node-collateral

Submits a signed node collateral creation request. The collateral will be included in the next global snapshot. 
curl -X POST https://<node-host>:9000/node-collateral \
  -H "Content-Type: application/json" \
  -d '{
    "value": {
      "source": "DAG3hZTBgtb2iH9ZdLNvaKqPT4ZncCuW6uYxZack",
      "nodeId": "c7f9a08bdea7ff5f51c8af16e223a1d751bac9c541125d9aef5658e9b7597aee",
      "amount": 125000,
      "fee": 123,
      "tokenLockRef": "abc123...",
      "parent": { "ordinal": 0, "hash": "" }
    },
    "proofs": [
      { "id": "<public-key-hex>", "signature": "<ecdsa-der-hex>" }
    ]
  }'
Request body — SignedCreateNodeCollateral
​
value
object
required
The node collateral creation payload
​
proofs
array
required
Array of cryptographic signature proofs from the source address owner
Response 200 OK
​
hash
string
Hash of the accepted node collateral creation transaction
Response 400 Bad Request
​
errors
array
Array of error cause objects with message fields describing the rejection reason
Response 503 Service Unavailable Node is not in Ready state.

​
PUT /node-collateral

Withdraws an existing node collateral position. The locked tokens are released after the unlock period has elapsed. 
curl -X PUT https://<node-host>:9000/node-collateral \
  -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 — SignedWithdrawNodeCollateral Same envelope structure as POST /node-collateral but with a WithdrawNodeCollateral payload containing source, tokenLockRef, and parent. Response 200 OK
​
hash
string
Hash of the accepted node collateral 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 /node-collateral//info

Returns all node collateral positions (active and pending withdrawal) for a given address. 
curl https://<node-host>:9000/node-collateral/DAG3hZTBgtb2iH9ZdLNvaKqPT4ZncCuW6uYxZack/info
​
address
string
required
DAG wallet address to query
Response 200 OK
​
address
string
The queried wallet address
​
activeNodeCollaterals
array
Currently active node collateral positions
​
pendingWithdrawals
array
Collateral positions in the withdrawal pending state (same schema as activeNodeCollaterals)
Response 503 Service Unavailable Node is not in Ready state.

​
GET /node-collateral/last-reference/

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

Build docs developers (and LLMs) love

Get started for freeTalk to us