> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload Reserve Attestation

> Upload monthly reserve attestation reports signed by CPA and officers

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

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_ADMIN_TOKEN
X-HMAC-Signature: YOUR_HMAC_SIGNATURE
X-Admin-Certificate: YOUR_ADMIN_CERT
```

## Request Body

<ParamField body="attestation_date" type="string" required>
  The month/year of the attestation (YYYY-MM-DD format, must be last day of month)

  Example: `2025-07-31`
</ParamField>

<ParamField body="report_file" type="string" required>
  Base64 encoded PDF of the signed attestation report
</ParamField>

<ParamField body="report_hash" type="string" required>
  SHA-256 hash of the report file for integrity verification
</ParamField>

<ParamField body="auditor" type="object" required>
  CPA firm information

  <Expandable title="Auditor Object">
    <ParamField body="firm_name" type="string" required>
      Registered public accounting firm name
    </ParamField>

    <ParamField body="license_number" type="string" required>
      CPA license number
    </ParamField>

    <ParamField body="lead_auditor_name" type="string" required>
      Name of lead auditor
    </ParamField>

    <ParamField body="signature_date" type="string" required>
      Date auditor signed the report
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="officer_signatures" type="array" required>
  Array of C-suite officer signatures

  <Expandable title="Officer Signature Object">
    <ParamField body="name" type="string" required>
      Officer's full legal name
    </ParamField>

    <ParamField body="title" type="string" required>
      Officer title (CEO, CFO, etc.)
    </ParamField>

    <ParamField body="signature" type="string" required>
      Digital signature (base64 encoded)
    </ParamField>

    <ParamField body="signature_date" type="string" required>
      Date of signature
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reserve_summary" type="object" required>
  Summary of reserve composition

  <Expandable title="Reserve Summary">
    <ParamField body="total_reserves_usd" type="string" required>
      Total value of reserves in USD
    </ParamField>

    <ParamField body="total_supply_susd" type="string" required>
      Total ssUSD supply at attestation date
    </ParamField>

    <ParamField body="reserve_ratio" type="number" required>
      Reserves / Supply ratio (must be >= 1.0)
    </ParamField>

    <ParamField body="composition" type="object" required>
      Breakdown by asset type with amounts and percentages
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata

  <Expandable title="Metadata">
    <ParamField body="notes" type="string">
      Any additional notes or observations
    </ParamField>

    <ParamField body="material_changes" type="boolean">
      Whether there were material changes from previous month
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique attestation record ID
</ResponseField>

<ResponseField name="status" type="string">
  Upload status: "pending\_verification", "verified", "published"
</ResponseField>

<ResponseField name="public_url" type="string">
  Public URL where the attestation will be accessible
</ResponseField>

<ResponseField name="verification" type="object">
  Verification details

  <Expandable title="Verification Object">
    <ResponseField name="hash_verified" type="boolean">
      Whether file hash matches provided hash
    </ResponseField>

    <ResponseField name="signatures_verified" type="boolean">
      Whether all digital signatures are valid
    </ResponseField>

    <ResponseField name="compliance_check" type="string">
      Compliance validation status
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="publication_date" type="string">
  When the attestation will be publicly available
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of upload
</ResponseField>

<ResponseExample>
  ```json Example Request theme={null}
  {
    "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
    }
  }
  ```

  ```json Example Response theme={null}
  {
    "id": "att_2025_07_abc123",
    "status": "verified",
    "public_url": "https://reserves.stateset.com/attestations/2025-07-31.pdf",
    "verification": {
      "hash_verified": true,
      "signatures_verified": true,
      "compliance_check": "passed"
    },
    "publication_date": "2025-08-06T00:00:00Z",
    "created_at": "2025-08-05T14:30:00Z"
  }
  ```
</ResponseExample>

## 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

<CodeGroup>
  ```javascript Node.js theme={null}
  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;
    }
  }
  ```

  ```python Python theme={null}
  import requests
  import base64
  import hashlib
  import json
  from datetime import datetime

  class AttestationUploader:
      def __init__(self, admin_token, admin_cert):
          self.admin_token = admin_token
          self.admin_cert = admin_cert
          self.base_url = "https://api.stateset.com/v1/stablecoin"
          
      def upload_attestation(self, pdf_path, attestation_data):
          """Upload monthly reserve attestation"""
          
          # Read and encode PDF
          with open(pdf_path, 'rb') as f:
              pdf_content = f.read()
              pdf_base64 = base64.b64encode(pdf_content).decode('utf-8')
              
          # Calculate hash
          pdf_hash = hashlib.sha256(pdf_content).hexdigest()
          
          # Validate attestation date is last day of month
          date = datetime.strptime(attestation_data['date'], '%Y-%m-%d')
          next_month = date.replace(day=28) + datetime.timedelta(days=4)
          last_day = next_month - datetime.timedelta(days=next_month.day)
          
          if date.date() != last_day.date():
              raise ValueError("Attestation date must be last day of month")
              
          # Prepare request
          request_data = {
              "attestation_date": attestation_data['date'],
              "report_file": pdf_base64,
              "report_hash": pdf_hash,
              "auditor": attestation_data['auditor'],
              "officer_signatures": attestation_data['signatures'],
              "reserve_summary": attestation_data['summary'],
              "metadata": attestation_data.get('metadata', {})
          }
          
          # Generate HMAC signature
          hmac_signature = self.generate_hmac(request_data)
          
          headers = {
              "Authorization": f"Bearer {self.admin_token}",
              "X-HMAC-Signature": hmac_signature,
              "X-Admin-Certificate": self.admin_cert,
              "Content-Type": "application/json"
          }
          
          try:
              response = requests.post(
                  f"{self.base_url}/attestation/upload",
                  json=request_data,
                  headers=headers
              )
              response.raise_for_status()
              
              result = response.json()
              print(f"Attestation uploaded successfully!")
              print(f"ID: {result['id']}")
              print(f"Status: {result['status']}")
              print(f"Public URL: {result['public_url']}")
              
              return result
              
          except requests.exceptions.RequestException as e:
              print(f"Upload failed: {e}")
              if hasattr(e, 'response') and e.response:
                  print(f"Error details: {e.response.json()}")
              raise

  # Example usage
  uploader = AttestationUploader("YOUR_ADMIN_TOKEN", "YOUR_ADMIN_CERT")

  attestation_data = {
      "date": "2025-07-31",
      "auditor": {
          "firm_name": "Ernst & Young LLP",
          "license_number": "CPA-123456",
          "lead_auditor_name": "Sarah Johnson",
          "signature_date": "2025-08-05"
      },
      "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"
          }
      ],
      "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}
          }
      }
  }

  uploader.upload_attestation("july_2025_attestation.pdf", attestation_data)
  ```
</CodeGroup>