Skip to content
FSCO API Docs

Stablecoin Management

Summary

This guide will take you through the required steps to create and manage a stablecoin on the FSCO platform.

By the end of this guide, you will have completed the following:

  1. Created and Deployed a new Stablecoin
  2. Added permissioned roles to the stablecoin
  3. Created and uploaded documents for attestations
  4. Created attestations for minting and burning
  5. Verified attestations
  6. Used verified attestations to mint and burn stablecoin tokens
  7. Viewed stablecoin transaction history

Creating a Stablecoin

To create a new Stablecoin, you will use the FSCO Stablecoin API. UI support is coming soon.

When creating a stablecoin, you’ll need to provide details about the token and its backing currency:

Deploying a Stablecoin
// Deploy a new stablecoin
const response = await fetch('https://api.fsco.io/v2/stablecoin/deploy', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    name: 'Rivendell Gold',
    symbol: 'RGLD',
    decimals: 8,
    adminWalletId: '123e4567-e89b-12d3-a456-426614174000', // Admin wallet UUID (created in the FSCO Portal)
    backingCurrency: 'United States Dollar',
    backingCurrencySymbol: '$'
    // Optional parameters:
    // factoryContractDeploymentId: '123e4567-e89b-12d3-a456-426614174009', // Custom factory contract
    // chainId: 31337 // Target blockchain network ID
  })
});


const result = await response.json();
console.log(result);
// {
//   stablecoinId: '123e4567-e89b-12d3-a456-426614174003'
// }

Understanding Stablecoin Roles

The FSCO platform uses a role-based permission system to manage stablecoin operations. There are two contract types, each with its own set of roles:

Attestation Manager roles

RoleAbility
DEFAULT_ADMIN_ROLEManage contract settings and assign other roles
SUBMITTER_ROLESubmit new attestation requests
VERIFIER_ROLEVerify and approve attestation requests

Collateralised Token roles

RoleAbility
DEFAULT_ADMIN_ROLEManage contract settings and assign other roles
MINTER_ROLECreate new tokens using verified attestations
BURNER_ROLEBurn tokens using verified attestations
PAUSER_ROLETemporarily freeze all token transfers
BLACKLISTER_ROLEBlock specific addresses from transferring tokens

Managing Roles

You can add and remove roles for your stablecoin using the role management API:

Adding a Role to a Wallet
// Add a role to a wallet
const addRoleResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/role', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    type: 'ATTESTATION_MANAGER', // or 'COLLATERALISED_TOKEN'
    role: 'SUBMITTER_ROLE', // Role to assign
    roleWalletId: '123e4567-e89b-12d3-a456-426614174001', // Wallet to receive the role
    signerWalletId: '123e4567-e89b-12d3-a456-426614174000' // Admin wallet signing the transaction
  })
});
Removing a Role from a Wallet
// Remove a role from a wallet
const removeRoleResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/role', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    type: 'ATTESTATION_MANAGER', // or 'COLLATERALISED_TOKEN'
    role: 'SUBMITTER_ROLE', // Role to remove
    roleWalletId: '123e4567-e89b-12d3-a456-426614174001', // Wallet to lose the role
    signerWalletId: '123e4567-e89b-12d3-a456-426614174000' // Admin wallet signing the transaction
  })
});
Listing Roles for a Stablecoin
// List all roles for a stablecoin
const getRolesResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/roles', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your-token>'
  }
});


const roles = await getRolesResponse.json();
// {
//   roles: [
//     {
//       type: 'ATTESTATION_MANAGER',
//       role: 'DEFAULT_ADMIN_ROLE',
//       walletId: '123e4567-e89b-12d3-a456-426614174000'
//     },
//     {
//       type: 'ATTESTATION_MANAGER',
//       role: 'SUBMITTER_ROLE',
//       walletId: '123e4567-e89b-12d3-a456-426614174001'
//     }
//     // ...more roles
//   ]
// }
### The Attestation Process


Stablecoins on the FSCO platform require attestations to mint or burn tokens. This ensures that all token operations are backed by verifiable evidence. The attestation workflow follows this process:


1. **Create Attestation**: Submit a request to mint or burn tokens with supporting documentation
2. **Verify Attestation**: An authorized verifier approves or rejects the attestation
3. **Use Attestation**: Execute the mint or burn operation using the verified attestation


<Aside type="note">
    An attestation passes through several states during its lifecycle:
    - **pending**: Initial state when created
    - **submitted**: Submitted with all required documentation
    - **verified**: Approved by a verifier
    - **rejected**: Declined by a verifier
    - **used**: Consumed in a mint or burn transaction
</Aside>


#### 1. Uploading Attestation Documents


Before creating an attestation, you'll typically need to upload supporting documents:


```ts title="Uploading an Attestation Document"
// Upload a document for an attestation
// This example uses the FormData API - in a browser context, you would typically use a file input
const formData = new FormData();
formData.append('file', fileBlob, 'bank-statement.pdf');


const uploadResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestation/documents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your-token>'
  },
  body: formData
});


const uploadResult = await uploadResponse.json();
// {
//   blobId: '123e4567-e89b-12d3-a456-426614174005'
// }

2. Creating an Attestation

With your documents uploaded, you can create an attestation request:

Creating a Mint Attestation
// Create a mint attestation
const createAttestationResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    type: 'mint', // or 'burn'
    amount: '1000000000', // Amount in smallest unit (based on decimals)
    destinationWalletId: '123e4567-e89b-12d3-a456-426614174006', // Required for mint operations
    // sourceWalletId: '123e4567-e89b-12d3-a456-426614174006', // Required for burn operations
    signerWalletId: '123e4567-e89b-12d3-a456-426614174001', // Wallet with SUBMITTER_ROLE
    transactionReference: 'WIRE-1234567890',
    transactionDate: new Date().toISOString(),
    additionalNotes: 'Wire transfer from Bank of America account ending in 1234',
    documents: [
      { blobId: '123e4567-e89b-12d3-a456-426614174005' }
    ]
  })
});


const attestationResult = await createAttestationResponse.json();
// {
//   attestationId: '123e4567-e89b-12d3-a456-426614174007'
// }

3. Verifying an Attestation

Once an attestation is created, it must be verified by a wallet with the VERIFIER_ROLE:

Verifying an Attestation
// Verify (approve) an attestation
const verifyResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestation/123e4567-e89b-12d3-a456-426614174007/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    approved: true,
    notes: 'Verified bank statement and confirmed wire transfer details',
    signerWalletId: '123e4567-e89b-12d3-a456-426614174002' // Wallet with VERIFIER_ROLE
  })
});
Rejecting an Attestation
// Reject an attestation
const rejectResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestation/123e4567-e89b-12d3-a456-426614174007/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    approved: false,
    notes: 'Documentation is incomplete. Please provide additional evidence of the wire transfer.',
    signerWalletId: '123e4567-e89b-12d3-a456-426614174002' // Wallet with VERIFIER_ROLE
  })
});
#### 4. Using a Verified Attestation


After an attestation is verified, it can be used to mint or burn tokens:


```ts title="Using an Attestation to Mint or Burn Tokens"
// Use a verified attestation to mint or burn tokens
const useAttestationResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestation/123e4567-e89b-12d3-a456-426614174007/use', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <your-token>'
  },
  body: JSON.stringify({
    signerWalletId: '123e4567-e89b-12d3-a456-426614174008' // Wallet with MINTER_ROLE or BURNER_ROLE
  })
});
#### 5. Retrieving Attestation Details


You can retrieve the details of a specific attestation:


```ts title="Getting Attestation Details"
// Get attestation details
const attestationResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestation/123e4567-e89b-12d3-a456-426614174007', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your-token>'
  }
});


const attestationDetails = await attestationResponse.json();
// {
//   attestation: {
//     id: '123e4567-e89b-12d3-a456-426614174007',
//     stablecoinId: '123e4567-e89b-12d3-a456-426614174003',
//     type: 'mint',
//     status: 'verified',
//     amount: '1000000000',
//     destinationWalletId: '123e4567-e89b-12d3-a456-426614174006',
//     submitterWalletId: '123e4567-e89b-12d3-a456-426614174001',
//     verifierWalletId: '123e4567-e89b-12d3-a456-426614174002',
//     isVerified: true,
//     createdAt: '2023-10-20T14:30:45Z',
//     verifiedAt: '2023-10-20T15:15:20Z',
//     transactionReference: 'WIRE-1234567890',
//     transactionDate: '2023-10-20T10:00:00Z',
//     additionalNotes: 'Wire transfer from Bank of America account ending in 1234',
//     verificationReason: 'Verified bank statement and confirmed wire transfer details',
//     documents: [
//       {
//         id: '123e4567-e89b-12d3-a456-426614174099',
//         blobId: '123e4567-e89b-12d3-a456-426614174005',
//         submitterWalletId: '123e4567-e89b-12d3-a456-426614174001'
//       }
//     ]
//   }
// }
### Viewing Stablecoin Information


You can retrieve information about your stablecoin, including supply statistics and contract details:


```ts title="Getting Stablecoin Details"
// Get stablecoin details
const stablecoinResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your-token>'
  }
});


const stablecoinDetails = await stablecoinResponse.json();
// {
//   stablecoin: {
//     id: '123e4567-e89b-12d3-a456-426614174003',
//     name: 'Rivendell Gold',
//     symbol: 'RGLD',
//     decimals: 8,
//     circulatingSupply: '1000000000',
//     totalMinted: '1000000000',
//     totalBurned: '0',
//     backingCurrency: 'United States Dollar',
//     backingCurrencySymbol: '$',
//     factoryContractDeploymentId: '123e4567-e89b-12d3-a456-426614174009',
//     tokenContractDeploymentId: '123e4567-e89b-12d3-a456-426614174010',
//     attestationContractDeploymentId: '123e4567-e89b-12d3-a456-426614174011',
//     tokenContractAddress: '0x1234...',
//     attestationContractAddress: '0x5678...',
//     chainId: 31337
//   }
// }
### Listing Attestations


You can list attestations for your stablecoin with optional filtering by type and status:


```ts title="Listing Attestations"
// List attestations
const attestationsResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/attestations?type=mint&status=verified&page=1&pageSize=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your-token>'
  }
});


const attestations = await attestationsResponse.json();
// {
//   attestations: [
//     {
//       id: '123e4567-e89b-12d3-a456-426614174007',
//       type: 'mint',
//       status: 'verified',
//       amount: '1000000000',
//       destinationWalletId: '123e4567-e89b-12d3-a456-426614174006',
//       submitterWalletId: '123e4567-e89b-12d3-a456-426614174001',
//       verifierWalletId: '123e4567-e89b-12d3-a456-426614174002',
//       createdAt: '2023-10-20T14:30:45Z',
//       verifiedAt: '2023-10-20T15:15:20Z'
//       // Other attestation details...
//     }
//   ],
//   meta: {
//     page: 1,
//     pageSize: 10,
//     totalPages: 1,
//     totalCount: 1
//   }
// }
### Listing Stablecoins


You can retrieve a list of all stablecoins that you have access to:


```ts title="Listing Stablecoins"
// List all stablecoins
const stablecoinsResponse = await fetch('https://api.fsco.io/v2/stablecoin/list?page=1&pageSize=10', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your-token>'
  }
});


const stablecoins = await stablecoinsResponse.json();
// {
//   stablecoins: [
//     {
//       id: '123e4567-e89b-12d3-a456-426614174003',
//       name: 'Rivendell Gold',
//       symbol: 'RGLD',
//       decimals: 8,
//       circulatingSupply: '1000000000',
//       // Other stablecoin details...
//     }
//   ],
//   meta: {
//     page: 1,
//     pageSize: 10,
//     totalPages: 1,
//     totalCount: 1
//   }
// }
### Viewing Mint and Burn History


You can retrieve the history of mint and burn transactions for your stablecoin:


```ts title="Getting Mint/Burn History"
// Get mint/burn history
const historyResponse = await fetch('https://api.fsco.io/v2/stablecoin/123e4567-e89b-12d3-a456-426614174003/mint-burn-history', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <your-token>'
  }
});


const history = await historyResponse.json();
// {
//   transactions: [
//     {
//       id: '1',
//       type: 'mint',
//       amount: '1000000000',
//       walletId: '123e4567-e89b-12d3-a456-426614174008',
//       timestamp: '2023-10-20T15:30:45Z',
//       transactionHash: '0x1234567890'
//     }
//   ],
//   total: 1
// }
<Aside type="note">
  All financial amounts in the API are represented as strings to maintain precision, especially for large numbers. The actual value depends on the `decimals` parameter of your stablecoin.
</Aside>


This guide covers the basic operations for managing stablecoins on the FSCO platform. For more detailed information about specific endpoints and request parameters, refer to the [API Reference](/stablecoin/operations/stablecoindeploy).