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

# Issue ssUSD

> Mint new StateSet USD (ssUSD) stablecoins upon receipt of USD reserves

<Info>
  **Issuer Access Only**: This endpoint requires verified issuer status under the GENIUS Act. Contact [sales@stateset.com](mailto:sales@stateset.com) for issuer onboarding.
</Info>

## Overview

The issue endpoint allows authorized entities to mint new ssUSD tokens when USD funds are received and verified. Every ssUSD issued is backed 1:1 by USD reserves held in segregated accounts.

### Key Requirements

<CardGroup cols={2}>
  <Card title="Issuer Verification" icon="shield-check">
    Must be approved as a Federal Qualified Nonbank Payment Stablecoin Issuer
  </Card>

  <Card title="KYC/AML Compliance" icon="user-check">
    All issuances require completed KYC and passed AML checks
  </Card>

  <Card title="Reserve Verification" icon="bank">
    USD funds must be received and verified before issuance
  </Card>

  <Card title="API Permissions" icon="key">
    API key must have `stablecoin:issue` scope
  </Card>
</CardGroup>

## Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.stateset.com/v1/stablecoin/issue \
    -H "Authorization: Bearer sk_live_issuer_..." \
    -H "X-Issuer-Certificate: cert_..."
  ```

  ```javascript Node.js theme={null}
  const headers = {
    'Authorization': 'Bearer sk_live_issuer_...',
    'X-Issuer-Certificate': 'cert_...'
  };
  ```
</CodeGroup>

### Required Headers

| Header                 | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `Authorization`        | Bearer token with issuer permissions           |
| `X-Issuer-Certificate` | Issuer certificate for additional verification |

## Request Parameters

<ParamField body="recipient" type="string" required>
  The StateSet address to receive the issued ssUSD

  **Format**: `stateset1` followed by 39 characters

  **Example**: `stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu`
</ParamField>

<ParamField body="amount" type="string" required>
  Amount of ssUSD to issue in standard units (not micro units)

  **Format**: Decimal string with up to 2 decimal places

  **Examples**:

  * `"1000.00"` - Issue 1,000 ssUSD
  * `"50000.50"` - Issue 50,000.50 ssUSD

  **Limits**:

  * Minimum: \$100.00
  * Maximum: \$10,000,000.00 per transaction
</ParamField>

<ParamField body="reference_id" type="string" required>
  Unique identifier for this issuance. Used for idempotency.

  **Format**: Any unique string up to 64 characters

  **Example**: `"ISS-2024-001234"`

  <Warning>
    Reusing a reference\_id will return the original transaction instead of creating a new one.
  </Warning>
</ParamField>

<ParamField body="source_funds" type="object" required>
  Details about the USD funds backing this issuance

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      How the USD was received

      **Options**:

      * `bank_wire` - Fedwire transfer
      * `ach` - ACH transfer
      * `swift` - International SWIFT wire
      * `check` - Cashier's check
    </ParamField>

    <ParamField body="reference" type="string" required>
      Reference number from the payment system

      **Examples**:

      * Wire: `"FEDREF20240115ABC123"`
      * ACH: `"ACH-TRACE-123456"`
      * SWIFT: `"SWIFT-MT103-REF"`
    </ParamField>

    <ParamField body="amount_usd" type="string" required>
      USD amount received (must match issuance amount)
    </ParamField>

    <ParamField body="sending_institution" type="string" required>
      Name of the bank/institution that sent the funds
    </ParamField>

    <ParamField body="received_at" type="string" required>
      ISO 8601 timestamp when funds were received
    </ParamField>

    <ParamField body="verified" type="boolean" required>
      Whether the funds have been verified by operations team
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="compliance" type="object" required>
  Compliance verification details

  <Expandable title="properties">
    <ParamField body="kyc_status" type="string" required>
      KYC verification status

      **Options**: `verified`, `pending`, `rejected`
    </ParamField>

    <ParamField body="kyc_provider" type="string" required>
      KYC provider used

      **Options**: `jumio`, `onfido`, `trulioo`
    </ParamField>

    <ParamField body="kyc_id" type="string" required>
      KYC verification ID from provider
    </ParamField>

    <ParamField body="aml_status" type="string" required>
      AML screening status

      **Options**: `clear`, `pending_review`, `flagged`
    </ParamField>

    <ParamField body="aml_provider" type="string" required>
      AML provider used

      **Options**: `chainalysis`, `elliptic`, `coinfirm`
    </ParamField>

    <ParamField body="jurisdiction" type="string" required>
      Recipient's jurisdiction (ISO 3166-1 alpha-2)

      **Example**: `"US"`, `"GB"`, `"CA"`
    </ParamField>

    <ParamField body="sanctions_check" type="boolean" required>
      Whether OFAC/sanctions screening passed
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="purpose" type="string">
  Purpose code for the issuance

  **Options**:

  * `general` - General business operations
  * `merchant_settlement` - E-commerce merchant payouts
  * `payroll` - Employee salary payments
  * `vendor_payment` - B2B vendor payments
  * `treasury` - Corporate treasury operations
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for record keeping

  **Example**:

  ```json theme={null}
  {
    "customer_id": "cust_123",
    "internal_ref": "MINT-2024-001",
    "notes": "Monthly merchant settlement"
  }
  ```
</ParamField>

## Response

<ResponseField name="issuance" type="object">
  The issuance details

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique issuance identifier

      **Example**: `"iss_1a2b3c4d5e6f7g8h"`
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the issuance

      **Values**: `pending`, `processing`, `completed`, `failed`
    </ResponseField>

    <ResponseField name="recipient" type="string">
      The address that received ssUSD
    </ResponseField>

    <ResponseField name="amount" type="object">
      Amount details

      <Expandable title="properties">
        <ResponseField name="value" type="string">
          Amount in ssUSD
        </ResponseField>

        <ResponseField name="denom" type="string">
          Always `"ssusd"`
        </ResponseField>

        <ResponseField name="usd_value" type="string">
          USD equivalent (always matches value for ssUSD)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="reference_id" type="string">
      Your provided reference ID
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transaction" type="object">
  Blockchain transaction details

  <Expandable title="properties">
    <ResponseField name="hash" type="string">
      Transaction hash on StateSet

      **Example**: `"B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"`
    </ResponseField>

    <ResponseField name="block_height" type="number">
      Block number containing the transaction
    </ResponseField>

    <ResponseField name="gas_used" type="string">
      Gas consumed by the transaction
    </ResponseField>

    <ResponseField name="explorer_url" type="string">
      Link to view on block explorer
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reserve_update" type="object">
  Reserve balance update details

  <Expandable title="properties">
    <ResponseField name="total_supply" type="string">
      New total ssUSD supply
    </ResponseField>

    <ResponseField name="total_reserves" type="string">
      Total USD reserves after update
    </ResponseField>

    <ResponseField name="reserve_ratio" type="string">
      Should always be "1.0000" or higher
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.stateset.com/v1/stablecoin/issue \
    -H "Authorization: Bearer sk_live_issuer_..." \
    -H "X-Issuer-Certificate: cert_..." \
    -H "Content-Type: application/json" \
    -d '{
      "recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
      "amount": "50000.00",
      "reference_id": "ISS-2024-001234",
      "source_funds": {
        "type": "bank_wire",
        "reference": "FEDREF20240115ABC123",
        "amount_usd": "50000.00",
        "sending_institution": "Chase Bank",
        "received_at": "2024-01-15T09:30:00Z",
        "verified": true
      },
      "compliance": {
        "kyc_status": "verified",
        "kyc_provider": "jumio",
        "kyc_id": "KYC-ABC-123456",
        "aml_status": "clear",
        "aml_provider": "chainalysis",
        "jurisdiction": "US",
        "sanctions_check": true
      },
      "purpose": "merchant_settlement",
      "metadata": {
        "customer_id": "cust_123456",
        "batch": "SETTLE-2024-01-15"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  import { StateSet } from '@stateset/sdk';

  const stateset = new StateSet({
    apiKey: process.env.STATESET_ISSUER_KEY,
    issuerCert: process.env.ISSUER_CERTIFICATE
  });

  async function issueSSUSD() {
    try {
      const issuance = await stateset.stablecoin.issue({
        recipient: 'stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu',
        amount: '50000.00',
        reference_id: 'ISS-2024-001234',
        source_funds: {
          type: 'bank_wire',
          reference: 'FEDREF20240115ABC123',
          amount_usd: '50000.00',
          sending_institution: 'Chase Bank',
          received_at: '2024-01-15T09:30:00Z',
          verified: true
        },
        compliance: {
          kyc_status: 'verified',
          kyc_provider: 'jumio',
          kyc_id: 'KYC-ABC-123456',
          aml_status: 'clear',
          aml_provider: 'chainalysis',
          jurisdiction: 'US',
          sanctions_check: true
        },
        purpose: 'merchant_settlement',
        metadata: {
          customer_id: 'cust_123456',
          batch: 'SETTLE-2024-01-15'
        }
      });
      
      console.log('Issuance completed:', issuance.id);
      console.log('Transaction hash:', issuance.transaction.hash);
      console.log('New total supply:', issuance.reserve_update.total_supply);
      
    } catch (error) {
      console.error('Issuance failed:', error.message);
      
      if (error.code === 'insufficient_reserve_verification') {
        console.error('USD funds not verified. Check with operations team.');
      }
    }
  }
  ```

  ```python Python theme={null}
  from stateset import StateSet
  from datetime import datetime

  stateset = StateSet(
      api_key=os.getenv('STATESET_ISSUER_KEY'),
      issuer_cert=os.getenv('ISSUER_CERTIFICATE')
  )

  def issue_ssusd():
      try:
          issuance = stateset.stablecoin.issue(
              recipient='stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu',
              amount='50000.00',
              reference_id='ISS-2024-001234',
              source_funds={
                  'type': 'bank_wire',
                  'reference': 'FEDREF20240115ABC123',
                  'amount_usd': '50000.00',
                  'sending_institution': 'Chase Bank',
                  'received_at': '2024-01-15T09:30:00Z',
                  'verified': True
              },
              compliance={
                  'kyc_status': 'verified',
                  'kyc_provider': 'jumio',
                  'kyc_id': 'KYC-ABC-123456',
                  'aml_status': 'clear',
                  'aml_provider': 'chainalysis',
                  'jurisdiction': 'US',
                  'sanctions_check': True
              },
              purpose='merchant_settlement',
              metadata={
                  'customer_id': 'cust_123456',
                  'batch': 'SETTLE-2024-01-15'
              }
          )
          
          print(f'Issuance completed: {issuance.id}')
          print(f'Transaction hash: {issuance.transaction.hash}')
          print(f'New total supply: {issuance.reserve_update.total_supply}')
          
      except Exception as e:
          print(f'Issuance failed: {str(e)}')
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "issuance": {
      "id": "iss_1a2b3c4d5e6f7g8h",
      "status": "completed",
      "recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
      "amount": {
        "value": "50000.00",
        "denom": "ssusd",
        "usd_value": "50000.00"
      },
      "reference_id": "ISS-2024-001234",
      "created_at": "2024-01-15T10:30:05Z"
    },
    "transaction": {
      "hash": "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2",
      "block_height": 1234567,
      "gas_used": "125000",
      "explorer_url": "https://explorer.stateset.com/tx/B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"
    },
    "reserve_update": {
      "total_supply": "125000000.00",
      "total_reserves": "125500000.00",
      "reserve_ratio": "1.0040"
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "code": "insufficient_reserve_verification",
      "message": "Source funds have not been verified. Please contact operations team.",
      "param": "source_funds.verified",
      "details": {
        "wire_reference": "FEDREF20240115ABC123",
        "expected_amount": "50000.00",
        "verification_status": "pending"
      }
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                                | Description                       | Resolution                          |
| ----------------------------------- | --------------------------------- | ----------------------------------- |
| `unauthorized_issuer`               | Not authorized to issue ssUSD     | Contact sales for issuer onboarding |
| `insufficient_permissions`          | API key lacks issue permissions   | Use an issuer API key               |
| `duplicate_reference`               | Reference ID already used         | Use a unique reference ID           |
| `insufficient_reserve_verification` | USD funds not verified            | Wait for operations to verify wire  |
| `compliance_check_failed`           | KYC/AML check failed              | Resolve compliance issues           |
| `invalid_recipient`                 | Invalid StateSet address          | Check address format                |
| `amount_mismatch`                   | Source funds don't match issuance | Ensure amounts match exactly        |
| `rate_limit_exceeded`               | Too many requests                 | Implement exponential backoff       |

## Compliance & Regulations

<Warning>
  All issuances must comply with GENIUS Act requirements. Failure to maintain proper reserves or accurate reporting may result in criminal penalties.
</Warning>

### Monthly Attestation Impact

Each issuance updates the reserve balance that must be attested monthly:

* Increases total ssUSD supply
* Must be backed by verified USD reserves
* Included in monthly CPA audit
* Subject to regulatory review

### Record Keeping

All issuance records are maintained for 7 years including:

* Source fund documentation
* KYC/AML verification records
* Transaction details
* Reserve balance updates

## Best Practices

<AccordionGroup>
  <Accordion title="Verify Funds First">
    Always ensure USD funds are received and verified before attempting issuance. The API will reject issuances without verified backing funds.
  </Accordion>

  <Accordion title="Use Idempotency">
    Always provide a unique `reference_id`. This prevents accidental duplicate issuances and allows safe retries.
  </Accordion>

  <Accordion title="Monitor Reserve Ratio">
    After each issuance, verify the `reserve_ratio` remains at or above 1.0000. This ensures full backing.
  </Accordion>

  <Accordion title="Implement Webhooks">
    Set up webhooks to receive real-time notifications about issuance status, especially for large amounts.
  </Accordion>
</AccordionGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Redeem ssUSD" icon="minus-circle" href="/stablecoin/redeem">
    Burn ssUSD and withdraw USD reserves
  </Card>

  <Card title="View Reserves" icon="shield-check" href="/stablecoin/reserves">
    Check current reserve composition
  </Card>

  <Card title="Transfer ssUSD" icon="arrow-right" href="/stablecoin/transfer">
    Transfer between addresses
  </Card>

  <Card title="Attestations" icon="file-certificate" href="/stablecoin/attestation">
    View monthly reserve reports
  </Card>
</CardGroup>