Anchoring Status

Anchoring a file on the blockchain does not finish inside the API call. The create request returns as soon as the anchoring transaction has been submitted, and the transaction is confirmed afterwards. The file’s status tells you which side of that line it is on. To find out when a file has been anchored, check its status until it settles.

How It Works

You create the file - the response is immediate and carries the transactionHash of the anchoring transaction
The file starts as PENDING while that transaction is confirmed
You read the file again, until its status is REGISTERED or FAILED

File Statuses

Status	Meaning
`PENDING`	The anchoring transaction has been submitted and is not confirmed yet. This is the status right after the file is created.
`REGISTERED`	The transaction was confirmed. The file is anchored.
`FAILED`	The anchoring transaction did not complete. The file is not anchored.

A file in REGISTERED or FAILED is no longer waiting on a confirmation, so there is nothing left to wait for. A REGISTERED file stays REGISTERED. Confirmation depends on the blockchain network, so do not assume a fixed delay between PENDING and REGISTERED.

Retrying the anchoring

A file that is FAILED - or that stays PENDING far longer than you expect - can be sent for anchoring again from the file’s actions menu in the ROOTKey dashboard. This submits a new transaction: the file goes back to PENDING and its transactionHash changes.

Following a File

Create the file

Call Create file. The response contains the chainId and the transactionHash of the anchoring transaction.

{
  "chainId": 137,
  "transactionHash": "0xabc123..."
}

Find the file's ID

The create response does not include the file’s ID. List the files of the vault - newest first by default - and take the id of the file you just created. Match on name, and confirm in the next step that the transactionHash is the one you were given. If the same name was uploaded more than once, the hash is what tells them apart.

Check the status

Call Fetch file with the fileId and the ownerVault. The status is in file.status, and file.transactionHash is the anchoring transaction.

Repeat until it settles

Keep checking while the status is PENDING. Stop at REGISTERED or FAILED.

Checking many files at once

To follow several uploads without a request per file, list the vault’s files with the status filter set to pending. Files that are no longer in that list have settled - read them to see whether each is REGISTERED or FAILED.

curl "https://api.rootkey.ai/api-v1/platform/files?vaultAddress=0xYourVault&status=pending" \
  -H "x-api-key: YOUR_API_KEY"

The status filter takes lowercase values - pending, registered and error - where error matches the files whose status is FAILED.

Example

import time
import requests

BASE_URL = "https://api.rootkey.ai/api-v1"
HEADERS = {"x-api-key": "YOUR_API_KEY"}


def wait_for_anchor(file_id: str, vault_address: str, give_up_after_s: int = 600) -> str:
    """Return REGISTERED or FAILED, once the file has settled."""
    delay = 2
    deadline = time.monotonic() + give_up_after_s

    while time.monotonic() < deadline:
        response = requests.get(
            f"{BASE_URL}/platform/files/{file_id}",
            params={"ownerVault": vault_address},
            headers=HEADERS,
            timeout=30,
        )

        # A 429, or a 503 on a read like this one, is safe to repeat after the wait
        if response.status_code in (429, 503):
            time.sleep(int(response.headers.get("Retry-After", delay)))
            continue

        response.raise_for_status()
        status = response.json()["file"]["status"]

        if status in ("REGISTERED", "FAILED"):
            return status

        time.sleep(delay)
        delay = min(delay * 2, 30)

    raise TimeoutError(f"File {file_id} is still PENDING")

Best Practices

Do not hold the upload request open Store the file’s ID and transactionHash when you create it, and check the status from a background job or a later request. Your user-facing request does not need to wait for the anchor. Back off between checks Start with a short delay and make it longer after each response that is still PENDING, as the example does. A tight loop adds load without making the anchor confirm sooner. Respect the rate limits and your quota Every check is an API request, so it counts towards your plan’s rate limit and request quota. On a 429, or a 503 to a read like this one, wait the number of seconds in the Retry-After header and check again. A request refused with usage_limit_exceeded is different: checking again does not help until the quota resets or the plan changes. See Rate Limits. Treat PENDING as not yet proven Until the status is REGISTERED, do not present the file as anchored or rely on it as evidence. Handle FAILED A FAILED file has not been anchored, so do not rely on it. Retry the anchoring from the dashboard, and if it keeps failing contact [email protected] with the file ID.

Introduction

Quickstart

Connectors

Integrations

Ecosystem Guides

Protocols

RKP-1 - Full On-Chain

RKP-2 - Off-Chain

RKP-3 - Hybrid

Data Sovereignty

Data Retention

Deployment Methods

On-Premise Installation

Developer Resources

Additional Resources

Anchoring Status

How It Works

File Statuses

Retrying the anchoring

Following a File

Checking many files at once

Example

Best Practices

​How It Works

​File Statuses

​Retrying the anchoring

​Following a File

​Checking many files at once

​Example

​Best Practices

How It Works

File Statuses

Retrying the anchoring

Following a File

Checking many files at once

Example

Best Practices