Skip to main content

Select the Environment you want to work withEnvironment:

This API is being released as part of an upcoming version.

The upcoming version is not backward compatible with the current stable version. You can find the details of the upcoming release and affected endpoints in the change log. Please contact eu-ebsi@ec.europa.eu if this upcoming release might cause a high impact on either an ongoing development or a piloting demonstration.

JSON-RPC API

Last updated on Mar 4, 2025

POST /timestamp/v5/jsonrpc

The JSON-RPC API provides methods assisting the construction of blockchain transactions for Timestamp operations, and interaction with the ledger.

Request

application/json

Bodyrequired

The body follows the JSON-RPC 2.0 specification.

It requires the following fields:

jsonrpc: must be exactly "2.0"
method: method to be invoked
params: method parameters
id: identifier established by the client

API Methods

insertHashAlgorithm

Call to build an unsigned transaction to insert a new hash algorithm. Requires admin rights.

Parameters:

from: Ethereum address of the signer
outputLength: hash output length (in bits)
ianaName: IANA name of the hash algorithm
oid: object identifier (OID)
status: status of the algorithm (1 = active, 2 = revoked)
multiHash: multihash name

updateHashAlgorithm

Call to build an unsigned transaction to update a hash algorithm. Requires admin rights.

Parameters:

from: Ethereum address of the signer
hashAlgorithmId: ID of the hash algorithm to update
outputLength: hash output length (in bits)
ianaName: IANA name of the hash algorithm
oid: object identifier (OID)
status: status of the algorithm (1 = active, 2 = revoked)
multiHash: multihash name

timestampHashes

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to timestamp hashes. It's possible to insert up to 3 hashes in a single transaction.

Parameters:

from: Ethereum address of the signer
hashAlgorithmIds: Array of hash algorithms ids used (up to 3)
hashValues: Array of hashes (up to 3)
timestampData (optional): Timestamp data. This field must be a JSON stringified and converted into hex string

timestampRecordHashes

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to timestamp data and create a record of it with some info. It's possible to insert up to 3 hashes in a single transaction.

Parameters:

from: Ethereum address of the signer
hashAlgorithmIds: Array of hash algorithms ids used (up to 3)
hashValues: Array of hashes (up to 3)
timestampData (optional): Timestamp data. This field must be a JSON stringified and converted into hex string
versionInfo: Version info. This field must be a JSON stringified and converted into hex string

timestampVersionHashes

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to timestamp hashes and store them under the given record. It's possible to insert up to 3 hashes in a single transaction. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
versionHash: Version hash to update
hashAlgorithmIds: Array of hash algorithms ids used (up to 3)
hashValues: Array of hashes (up to 3)
timestampData (optional): Timestamp data. This field must be a JSON stringified and converted into hex string
versionInfo: Version info. This field must be a JSON stringified and converted into hex string

insertRecordOwner

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to insert a record owner. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
recordId: Record ID to update
ownerId: Ethereum address of new owner
notBefore: Point in time when the owner becomes valid. It should be defined in epoch time.
notAfter: Point in time when the owner becomes invalid. It should be defined in epoch time. For indefinite time set 0.

revokeRecordOwner

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to revoke a record owner. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
recordId: Record ID to update
ownerId: Ethereum address of the owner to revoke

timestampRecordVersionHashes

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to timestamp data and link it to a new version of an existing record. It's possible to insert up to 3 hashes in a single transaction. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
recordId: Record ID to update
hashAlgorithmIds: Array of hash algorithms ids used (up to 3)
hashValues: Array of hashes (up to 3)
timestampData (optional): Timestamp data. This field must be a JSON stringified and converted into hex string
versionInfo: Version info. This field must be a JSON stringified and converted into hex string

appendRecordVersionHashes

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to timestamp data and link it to an existing version of a record. It's possible to insert up to 3 hashes in a single transaction. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
recordId: Record ID to update
versionId: Version ID to update
hashAlgorithmIds: Array of hash algorithms ids used (up to 3)
hashValues: Array of hashes (up to 3)
timestampData (optional): Timestamp data. This field must be a JSON stringified and converted into hex string
versionInfo: Version info. This field must be a JSON stringified and converted into hex string

detachRecordVersionHash

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to detach a hash from the timestamps ids of a version of an existing record. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
recordId: Record ID to update
versionId: Version ID to update
versionHash: Version hash to update
hashValue: Hash value to detach

insertRecordVersionInfo

Requires an access token with timestamp_write scope.

Call to build an unsigned transaction to to insert new info to a version of an existing record. This method can be called only by record owners.

Parameters:

from: Ethereum address of the signer
recordId: Record ID to update
versionId: Version ID to update
versionInfo: Version info. This field must be a JSON stringified and converted into hex string

sendSignedTransaction

Requires an access token with timestamp_write scope.

Sends a signed transaction to the blockchain and returns the hash of the transaction.

Warning: the transaction is not immediately processed. Make sure to check that the transaction has been successfully included in a block before moving on.

You can get the receipt of the transaction by calling the eth_getTransactionReceipt method of Ledger API's Besu endpoint.

Receipts for pending transactions are not available, therefore you will have to wait until the transaction has been processed — usually a few seconds. We recommend you to poll the eth_getTransactionReceipt method until the receipt is available.

Once the receipt is available, you can check the status field to know if the transaction succeeded (0x1) or failed (0x0). If the transaction failed, the revertReason field will give you insights about the reason for the failure. You can learn more about the format of the revert reason in Besu's documentation.

Note that the REST endpoints may not return the latest data immediately after the transaction is included in a block. The Graph has to process the block event and to update its database before returning the latest data. This can take a couple of seconds after the block is mined.

jsonrpc stringrequired

Must be exactly "2.0"

method stringrequired

Method that needs to be invoked

params object[]required

Array of parameters

id integerrequired

Identifier established by the client

Responses

200
400

Response

application/json

Schema
Build tx
Send Transaction

Schema

jsonrpc string

Must be exactly "2.0"

id integer

Same identifier established by the client in the call

result object

Result of the call

oneOf

MOD2

string

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x416e6e6162656c2e4c65652e452d412d506f652e",
    "to": "0xFde86148db58f57787C06BeAf63a9c3f789357b3",
    "data": "0x0000...",
    "nonce": "0x00",
    "chainId": "0x1b3b",
    "gasLimit": "0x10000",
    "gasPrice": "0x00",
    "value": "0x00"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

Bad request

application/problem+json

Schema
Bad Request

Schema

type uri

Default value: about:blank

An absolute URI that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type.

title string

A short summary of the problem type.

status int32

Possible values: >= 400 and <= 600

The HTTP status code generated by the origin server for this occurrence of the problem.

detail string

A human readable explanation specific to this occurrence of the problem.

instance uri

An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Bad request"
}

Loading...