DataRumeDocs

API Access ​

DataRume provides a secure API for programmatically accessing the assets stored in Data Rooms. This allows developers to integrate DataRume directly into their automated pipelines, CI/CD workflows, or custom applications.

The access flow consists of two mandatory steps, mirroring the on-chain security model:

  1. Start Order: Generate an access intent and commit it to the blockchain (Pay fee by burning a Data Token.
  2. Execute Order: Cryptographically prove identity to complete the handshake and retrieve files.

In addition to access, the token management operations like Minting and Transferring Data Tokens can also be performed via the API.

Prerequisites ​

To interact with the API, you will need:

  • RPC URL: connection to the blockchain node.
  • Private Key: of the wallet that holds valid Data Tokens.
  • Contract Address: of the Data Room's Data NFT you wish to access.

Helper Scripts ​

To simplify interacting with the blockchain and cryptographic signing, we provide two helper scripts (TypeScript). You can save these locally to run the commands below.

View scripts/send-tx.ts (Submits Transaction)
typescript
import "dotenv/config";
import { ethers } from "ethers";

// Usage: npx tsx scripts/send-tx.ts --rpc <url> --pk <private_key> --to <to_contract_address> --data <hex_data>

async function main() {
  const args = parseArgs();

  if (!args.rpc || !args.pk || !args.to || !args.data) {
    console.error(
      "Usage: npx tsx scripts/send-tx.ts --rpc <url> --pk <private_key> --to <to_address> --data <hex_data>",
    );
    process.exit(1);
  }

  try {
    const provider = new ethers.JsonRpcProvider(args.rpc);
    const wallet = new ethers.Wallet(args.pk, provider);

    console.log(`Using Wallet: ${wallet.address}`);
    const tx = {
      to: args.to,
      data: args.data,
      value: args.value ? BigInt(args.value) : 0n,
    };

    console.log("Sending transaction...");
    const response = await wallet.sendTransaction(tx);
    console.log(`Transaction sent! Hash: ${response.hash}`);

    console.log("Waiting for confirmation...");
    const receipt = await response.wait();
    console.log(`Status: ${receipt?.status === 1 ? "SUCCESS" : "FAILURE"}`);
  } catch (error: any) {
    console.error("Transaction Error:", error);
  }
}

function parseArgs() {
  const args = process.argv.slice(2);
  const result: any = {};
  for (let i = 0; i < args.length; i++) {
    if (args[i].startsWith("--")) {
      const key = args[i].substring(2);
      const value = args[i + 1];
      if (value && !value.startsWith("--")) {
        result[key] = value;
        i++;
      }
    }
  }
  return result;
}

main();
View scripts/sign-message.ts (Generates Consumer Signature)
typescript
import "dotenv/config";
import { ethers } from "ethers";

// Usage: npx tsx scripts/sign-message.ts --pk <private_key> --serviceIndex <hex_string>

async function main() {
  const args = parseArgs();

  if (!args.pk || !args.serviceIndex) {
    console.error(
      "Usage: npx tsx scripts/sign-message.ts --pk <private_key> --serviceIndex <hex_string>",
    );
    process.exit(1);
  }

  try {
    const wallet = new ethers.Wallet(args.pk);

    // Hash the Service Index exactly as the Smart Contract expects
    const consumerMessageHash = ethers.solidityPackedKeccak256(
      ["bytes32"],
      [args.serviceIndex],
    );

    // Sign the hash
    const signature = await wallet.signMessage(
      ethers.getBytes(consumerMessageHash),
    );

    console.log("\n--- SIGNATURE ---");
    console.log(signature);
    console.log("-----------------");
  } catch (error: any) {
    console.error("Signing Error:", error);
  }
}

function parseArgs() {
  const args = process.argv.slice(2);
  const result: any = {};
  for (let i = 0; i < args.length; i++) {
    if (args[i].startsWith("--")) {
      const key = args[i].substring(2);
      const value = args[i + 1];
      if (value && !value.startsWith("--")) {
        result[key] = value;
        i++;
      }
    }
  }
  return result;
}

main();

Access Flow ​

This flow allows you to view secured files.

Step 1: Start Order ​

Requests a transaction payload to verify token balance and burn 1 Data Token.

Parameters:

  • consumerAddress: The wallet address of the user attempting to access the file.
  • dataNFTAddress: The contract address of the Data Room (Data NFT) you want to access. This is visible in the TokenURI or Data Room URL.
Request
bash
curl --location 'https://staging.d2wtu9r4e20gde.amplifyapp.com/api/data-token/start-order' \
--header 'Content-Type: application/json' \
--data '{
    "consumerAddress": "0x2DE10718F08d1017f039dEF238Da6575b3A4C22A",
    "dataNFTAddress": "0x7B385a26025A834B79746f229bd02a9b94A3f682"
}'
Response Example
json
{
  "success": true,
  "serviceIndex": "0x3fc0f0866fc79ea4f90a95f0e33a50127cfcae40624d34c7e2263a2830f41a78",
  "txdata": {
    "from": "0x2DE10718F08d1017f039dEF238Da6575b3A4C22A",
    "to": "0x99FDEb76052E9Bff349ee15cF8b1AeC4a8374830",
    "data": "0x79d9d7f30000000...",
    "nonce": 12,
    "gasLimit": "86487",
    "gasPrice": "1500000007",
    "chainId": "600001"
  }
}

Action: Submit Transaction ​

Use the txdata from the response to submit the transaction to the chain.

Submit Transaction
bash
npx tsx scripts/send-tx.ts --rpc <rpc_url> --pk <private_key> --to <txdata.to> --data <txdata.data>

Step 2: Execute Order ​

Verifies the consumer signature and returns the unlocked files.

Parameters:

  • serviceIndex: The hexadecimal string returned in the Start Order response.
Generate Signature
bash
npx tsx scripts/sign-message.ts --pk <private_key> --serviceIndex <serviceIndex_from_step_1>

Parameters:

  • consumerAddress: The wallet address of the user (same as Step 1).
  • dataNFTAddress: The contract address of the Data Room (same as Step 1).
  • serviceIndex: The hexadecimal string returned in the Start Order response.
  • consumerSignature: The signature generated by signing the serviceIndex with your wallet's private key (use the sign-message.ts helper script).
Request
bash
curl --location 'https://staging.d2wtu9r4e20gde.amplifyapp.com/api/data-token/execute-order' \
--header 'Content-Type: application/json' \
--data '{
    "consumerAddress": "0x2DE10718F08d1017f039dEF238Da6575b3A4C22A",
    "dataNFTAddress": "0x7B385a26025A834B79746f229bd02a9b94A3f682",
    "serviceIndex": "0x3fc0f0866fc79ea4f90a95f0e33a50127cfcae40624d34c7e2263a2830f41a78",
    "consumerSignature": "0x7aa..."
}'
Response Example
json
{
  "success": true,
  "hash": "0xbcedf47fa0959605f9cbd336e8405cd3cc4113f7ea68048dac56d8c213ab4c12",
  "status": "EXECUTED",
  "metadata": {
    "name": "Project Alpha Documents",
    "files": [
      {
        "id": "e321...",
        "name": "financial-report-2024.pdf",
        "url": "https://datarume-vault.../file.pdf?X-Amz-Signature=..."
      }
    ]
  }
}

Token Management ​

These endpoints allow you to manage the Data Tokens for a room. Like the access flow, these APIs return a transaction payload (txdata) that must be signed and submitted to the network by the wallet owner.

Mint Tokens (Owner Only) ​

Generate new access tokens for a specific user.

Parameters:

  • senderAddress: The wallet address of the Data Room owner.
  • receiverAddress: The wallet address of the user who will receive the tokens.
  • amount: The number of tokens to mint (e.g., "1" for 1 full token).
  • dataNFTAddress: The contract address of the Data Room (Data NFT) to mint tokens for.
Request
bash
curl --location 'https://staging.d2wtu9r4e20gde.amplifyapp.com/api/data-token/mint' \
--header 'Content-Type: application/json' \
--data '{
    "senderAddress": "0xFA24d1dC2953D0d3c92d46b6f130a8C8F1115Ef7",
    "receiverAddress": "0x2DE10718F08d1017f039dEF238Da6575b3A4C22A",
    "amount": "2",
    "dataNFTAddress": "0xD0CdFa8b8119984495b958a0dec33a85D773FFb9"
}'
Response Example
json
{
  "success": true,
  "networkRpcUrl": "https://rpc-paypledge-private-staging.skutron.com",
  "txdata": {
    "from": "0xFA24d1dC2953D0d3c92d46b6f130a8C8F1115Ef7",
    "to": "0xb6Fd1AE2F14C1e82536A71649793b3a3177C7156",
    "data": "0x40c10f190000000000000000000000002de10718f08d1017f039def238da6575b3a4c22a0000000000000000000000000000000000000000000000001bc16d674ec80000",
    "nonce": 64,
    "gasLimit": "41689",
    "gasPrice": "1500000007",
    "chainId": "600001"
  }
}

Action: Submit Transaction ​

Submit the txdata using send-tx.ts.

Submit Transaction
bash
npx tsx scripts/send-tx.ts --rpc <rpc_url> --pk <private_key> --to <txdata.to> --data <txdata.data>

Transfer Tokens ​

Transfer existing access tokens from your wallet to another user.

Parameters:

  • senderAddress: The wallet address currently holding the tokens.
  • receiverAddress: The wallet address to transfer the tokens to.
  • amount: The number of tokens to transfer.
  • dataNFTAddress: The contract address of the Data Room (Data NFT) associated with these tokens.
Request
bash
curl --location 'https://staging.d2wtu9r4e20gde.amplifyapp.com/api/data-token/transfer' \
--header 'Content-Type: application/json' \
--data '{
    "senderAddress": "0x2DE10718F08d1017f039dEF238Da6575b3A4C22A",
    "receiverAddress": "0xb6Fd1AE2F14C1e82536A71649793b3a3177C7156",
    "amount": "2",
    "dataNFTAddress": "0xD0CdFa8b8119984495b958a0dec33a85D773FFb9"
}'
Response Example
json
{
  "success": true,
  "networkRpcUrl": "https://rpc-paypledge-private-staging.skutron.com",
  "txdata": {
    "from": "0x2DE10718F08d1017f039dEF238Da6575b3A4C22A",
    "to": "0xb6Fd1AE2F14C1e82536A71649793b3a3177C7156",
    "data": "0xa9059cbb0000000000000000000000006cb0c0ebfaad60bd59f4c32432247839fa4fbaf000000000000000000000000000000000000000000000000029a2241af62c0000",
    "nonce": 63,
    "gasLimit": "37385",
    "gasPrice": "1500000007",
    "chainId": "600001"
  }
}

Action: Submit Transaction ​

Submit the txdata to the network using send-tx.ts.

Submit Transaction
bash
npx tsx scripts/send-tx.ts --rpc <rpc_url> --pk <private_key> --to <txdata.to> --data <txdata.data>
Previous Chapter
Terminologies
 Next Chapter
Web3 & Networks