Push Data Endpoint

This endpoint allows you to associate arbitrary data with your Droplit instance. The data is pushed onto the Bitcoin blockchain within an OP_RETURN output.

Endpoint: POST /faucets/{droplitName}/push-data
- Replace {droplitName} with the name of your Droplit.
Authentication: Required (see Authentication)

Request Body

The request body must be a JSON object with the following structure:

{
  "data": ["string1", "string2", ...],
  "encoding": "utf8" // or "hex"
}

data: An array of strings. Each string will be a separate OP_RETURN push.
encoding: Specifies how the strings in the data array are encoded.
- "utf8": The strings are UTF-8 encoded.
- "hex": The strings are hex-encoded binary data.

Example: Curl

Replace <YOUR_WIF>, <DROPLIT_NAME>, <GENERATED_AUTH_TOKEN_VALUE>, and <YOUR_DROPLIT_API_URL> with your actual values.

# 1. Define variables (example)
PAYLOAD_BODY='{ "data": ["hello blockchain", "droplit rocks"], "encoding": "utf8" }'
PATHNAME_VALUE="/faucets/<DROPLIT_NAME>/push-data"
# Note: For the AUTH_TOKEN_VALUE, you need to generate it using a bitcoin-auth library.
# The message to sign is typically: PATHNAME_VALUE + PAYLOAD_BODY
# For curl, you might pre-generate this token.
AUTH_TOKEN_VALUE="<GENERATED_AUTH_TOKEN_VALUE>"
YOUR_DROPLIT_API_URL="http://localhost:8080" # Or your deployed URL
DROPLIT_NAME="your-droplit-name"

# 2. Make the request
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: ${AUTH_TOKEN_VALUE}" \
  -d "${PAYLOAD_BODY}" \
  ${YOUR_DROPLIT_API_URL}/faucets/${DROPLIT_NAME}/push-data

Example: JavaScript (Node.js using `node-fetch` and `bitcoin-auth`)

import fetch from 'node-fetch'; // npm install node-fetch
import { AuthConfig, getAuthToken } from 'bitcoin-auth'; // npm install bitcoin-auth, corrected to getAuthToken

async function pushDataToDroplit() {
  const droplitName = "your-droplit-name"; // Replace
  const userWIF = "your-private-key-wif"; // Replace
  const droplitApiUrl = "http://localhost:8080"; // Replace with your API URL

  const requestPath = `/faucets/${droplitName}/push-data`;
  const payload = {
    data: ["Droplit is awesome!", new Date().toISOString()],
    encoding: "utf8",
  };
  const bodyString = JSON.stringify(payload);

  const authConfig: AuthConfig = {
    privateKeyWif: userWIF,
    requestPath: requestPath,
    body: bodyString,
    // scheme defaults to 'bsm' in this version of bitcoin-auth
  };

  try {
    const authToken = await getAuthToken(authConfig); // Corrected to getAuthToken
    console.log('Auth Token:', authToken);

    const response = await fetch(`${droplitApiUrl}${requestPath}`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Auth-Token": authToken,
      },
      body: bodyString,
    });

    // It's good practice to check if the response is JSON before parsing
    let responseData;
    const contentType = response.headers.get("content-type");
    if (contentType && contentType.includes("application/json")) {
      responseData = await response.json();
    } else {
      responseData = await response.text(); // Or handle as appropriate
    }

    if (!response.ok) {
      console.error('API Error:', responseData);
      throw new Error(`HTTP error! Status: ${response.status} - ${responseData}`);
    }

    console.log("Push data successful:", responseData);
    // Expected response: { txid: "transaction_id", vouts: [0, 1, ...] }
  } catch (error) {
    console.error("Error pushing data:", error);
  }
}

pushDataToDroplit();

On success, the API returns a JSON object containing the transaction ID (txid) of the Bitcoin transaction that includes your data, and an array of vouts indicating the output indices of your data pushes.

{
  "txid": "abcdef123456...",
  "vouts": [1, 2] 
}

Error Responses

Common errors include:

400 Bad Request: Invalid request body or parameters.
401 Unauthorized: Missing or invalid X-Auth-Token.
500 Internal Server Error: Server-side issue.

The error response body will typically contain a JSON object with an error or message field.

Push Data Endpoint