Upload Reserve Attestation

Upload monthly reserve attestation reports signed by CPA and officers

POST /v1/stablecoin/attestation/upload

Upload Reserve Attestation

cURL

curl --request POST \
  --url https://api.stateset.com/v1/stablecoin/attestation/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "attestation_date": "<string>",
  "report_file": "<string>",
  "report_hash": "<string>",
  "auditor": {
    "firm_name": "<string>",
    "license_number": "<string>",
    "lead_auditor_name": "<string>",
    "signature_date": "<string>"
  },
  "officer_signatures": [
    {
      "name": "<string>",
      "title": "<string>",
      "signature": "<string>",
      "signature_date": "<string>"
    }
  ],
  "reserve_summary": {
    "total_reserves_usd": "<string>",
    "total_supply_susd": "<string>",
    "reserve_ratio": 123,
    "composition": {}
  },
  "metadata": {
    "notes": "<string>",
    "material_changes": true
  }
}
'

Example Request

{
  "attestation_date": "2025-07-31",
  "report_file": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx0ZXI...",
  "report_hash": "3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
  "auditor": {
    "firm_name": "Ernst & Young LLP",
    "license_number": "CPA-123456",
    "lead_auditor_name": "Sarah Johnson",
    "signature_date": "2025-08-05"
  },
  "officer_signatures": [
    {
      "name": "John Smith",
      "title": "Chief Executive Officer",
      "signature": "MGUCMQCrhPgP3VxqFqFwf+6n...",
      "signature_date": "2025-08-05"
    },
    {
      "name": "Jane Doe",
      "title": "Chief Financial Officer", 
      "signature": "MGUCMQDKhPbB4WyqGqGxg+7o...",
      "signature_date": "2025-08-05"
    }
  ],
  "reserve_summary": {
    "total_reserves_usd": "1234567890.00",
    "total_supply_susd": "1234567890.00",
    "reserve_ratio": 1.0,
    "composition": {
      "cash": {
        "amount": "123456789.00",
        "percentage": 10.0
      },
      "treasury_bills": {
        "amount": "864197523.00",
        "percentage": 70.0
      },
      "money_market_funds": {
        "amount": "185185183.50",
        "percentage": 15.0
      },
      "repo_agreements": {
        "amount": "61728394.50",
        "percentage": 5.0
      }
    }
  },
  "metadata": {
    "notes": "No material changes from previous month",
    "material_changes": false
  }
}

This endpoint is restricted to authorized administrators for uploading monthly reserve attestation reports as required by the GENIUS Act of 2025.

Authentication

This endpoint requires admin-level authentication with attestation upload permissions.

Authorization: Bearer YOUR_ADMIN_TOKEN
X-HMAC-Signature: YOUR_HMAC_SIGNATURE
X-Admin-Certificate: YOUR_ADMIN_CERT

Request Body

attestation_date · string · required

The month/year of the attestation (YYYY-MM-DD format, must be last day of month)

Example: 2025-07-31

report_file · string · required

Base64 encoded PDF of the signed attestation report

report_hash · string · required

SHA-256 hash of the report file for integrity verification

auditor · object · required

CPA firm information

Show Auditor Object

firm_name · string · required

Registered public accounting firm name

license_number · string · required

CPA license number

lead_auditor_name · string · required

Name of lead auditor

signature_date · string · required

Date auditor signed the report

officer_signatures · array · required

Array of C-suite officer signatures

Show Officer Signature Object

name · string · required

Officer’s full legal name

title · string · required

Officer title (CEO, CFO, etc.)

signature · string · required

Digital signature (base64 encoded)

signature_date · string · required

Date of signature

reserve_summary · object · required

Summary of reserve composition

Show Reserve Summary

total_reserves_usd · string · required

Total value of reserves in USD

total_supply_susd · string · required

Total ssUSD supply at attestation date

reserve_ratio · number · required

Reserves / Supply ratio (must be >= 1.0)

composition · object · required

Breakdown by asset type with amounts and percentages

metadata · object

Additional metadata

Show Metadata

notes · string

Any additional notes or observations

material_changes · boolean

Whether there were material changes from previous month

Response

id · string

Unique attestation record ID

status · string

Upload status: “pending_verification”, “verified”, “published”

public_url · string

Public URL where the attestation will be accessible

verification · object

Verification details

Show Verification Object

hash_verified · boolean

Whether file hash matches provided hash

signatures_verified · boolean

Whether all digital signatures are valid

compliance_check · string

Compliance validation status

publication_date · string

When the attestation will be publicly available

created_at · string

ISO 8601 timestamp of upload

Example Request

{
  "attestation_date": "2025-07-31",
  "report_file": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9GaWx0ZXI...",
  "report_hash": "3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
  "auditor": {
    "firm_name": "Ernst & Young LLP",
    "license_number": "CPA-123456",
    "lead_auditor_name": "Sarah Johnson",
    "signature_date": "2025-08-05"
  },
  "officer_signatures": [
    {
      "name": "John Smith",
      "title": "Chief Executive Officer",
      "signature": "MGUCMQCrhPgP3VxqFqFwf+6n...",
      "signature_date": "2025-08-05"
    },
    {
      "name": "Jane Doe",
      "title": "Chief Financial Officer", 
      "signature": "MGUCMQDKhPbB4WyqGqGxg+7o...",
      "signature_date": "2025-08-05"
    }
  ],
  "reserve_summary": {
    "total_reserves_usd": "1234567890.00",
    "total_supply_susd": "1234567890.00",
    "reserve_ratio": 1.0,
    "composition": {
      "cash": {
        "amount": "123456789.00",
        "percentage": 10.0
      },
      "treasury_bills": {
        "amount": "864197523.00",
        "percentage": 70.0
      },
      "money_market_funds": {
        "amount": "185185183.50",
        "percentage": 15.0
      },
      "repo_agreements": {
        "amount": "61728394.50",
        "percentage": 5.0
      }
    }
  },
  "metadata": {
    "notes": "No material changes from previous month",
    "material_changes": false
  }
}

Error Codes

Code	Description
400	Invalid request format or missing required fields
401	Unauthorized - Invalid admin credentials
403	Forbidden - Insufficient permissions
409	Conflict - Attestation for this month already exists
422	Validation failed - Invalid signatures or data
500	Internal server error

Compliance Notes

• Attestations must be uploaded within 5 business days of month end
• All signatures must be from authorized officers on file
• Criminal penalties apply for false or misleading attestations
• Reports are immutable once published

Code Examples

Node.js

const axios = require('axios');
const fs = require('fs');
const crypto = require('crypto');

async function uploadAttestation(pdfPath, attestationData) {
  // Read and encode PDF
  const pdfBuffer = fs.readFileSync(pdfPath);
  const pdfBase64 = pdfBuffer.toString('base64');
  
  // Calculate hash
  const hash = crypto.createHash('sha256');
  hash.update(pdfBuffer);
  const pdfHash = hash.digest('hex');
  
  // Prepare request
  const requestData = {
    attestation_date: attestationData.date,
    report_file: pdfBase64,
    report_hash: pdfHash,
    auditor: attestationData.auditor,
    officer_signatures: attestationData.signatures,
    reserve_summary: attestationData.summary
  };
  
  try {
    const response = await axios.post(
      'https://api.stateset.com/v1/stablecoin/attestation/upload',
      requestData,
      {
        headers: {
          'Authorization': 'Bearer YOUR_ADMIN_TOKEN',
          'X-HMAC-Signature': generateHMAC(requestData),
          'X-Admin-Certificate': 'YOUR_ADMIN_CERT',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Attestation uploaded:', response.data);
    console.log('Public URL:', response.data.public_url);
    
    return response.data;
  } catch (error) {
    console.error('Upload failed:', error.response.data);
    throw error;
  }
}