Skip to main content

Issue an Asset Tutorial

In this tutorial, we will walk through the steps to issue an asset on the Stellar test network.

note

If you'd like to interact with an asset issued on the Stellar network in smart contracts, you can create or deploy the Stellar Asset Contract for that asset.

Prerequisites​

You must ensure you have the required amount of XLM to create your issuing and distribution accounts and cover the minimum balance and transaction fees. If you’re issuing an asset on the testnet, you can fund your account by getting test XLM from friendbot. If you’re issuing an asset in production, you will need to acquire XLM from another wallet or exchange.

If you’d like to avoid your users having to deal with transaction fees, consider using fee-bump transactions. Read more in our Fee-Bump Transaction Encyclopedia Entry.

Learn about the testnet and mainnet in our Networks section.

Learn more about fees in our Fees, Resource Limits, and Metering section.

Foundational tools​

Issuer account keypair​

First, you must generate a unique keypair. The public key will act as your issuing identity on the network, while you use the secret key to sign transactions.

const issuerKeypair = StellarSdk.Keypair.random();

console.log("Issuer Public Key:", issuerKeypair.publicKey());
console.log("Issuer Secret Key:", issuerKeypair.secret());
info

Your account address will not change once you issue your asset, even if you modify its signers. Many issuers employ vanity public keys related to their asset. For instance, you might configure a custom signer in base32 like GASTRO...USD.

note

Many users secure their issuing account with cold storage techniques, such as a hardware wallet or multisignature setup. This adds an extra layer of protection by keeping your secret key offline or requiring multiple approvals for transactions.

Distribution account keypair​

Your asset can be issued and transferred between accounts through a payment, contract, or claimable balance. Although it is not required to create a distribution account, it is best practice, so we will do so in this example. Read more in our Issuing and Distribution Accounts section.

Three Operations​

Generate a new keypair​
const distributorKeypair = StellarSdk.Keypair.random();
Import an existing keypair​
const distributorKeypair = StellarSdk.Keypair.fromSecret(‘SCZANGBA5YHTNYVVV4C3U252E2B6P6F5T3U6MM63WBSBZATAQI3EBTQ4’)
Employ multiple signatures​
danger

Be careful when working with raw secret keys. If you don't have issuer trustline clawback enabled, any misstep here could permanently render assets lost. Many users put their first few projects on testnet or try out Quests which provide a low-stakes introductory sandbox.

Local asset object​

The asset object is a combination of your code and your issuing public key. After your issuance, anyone can search the network for your unique asset.

const astroDollar = new StellarSdk.Asset(
  "AstroDollar",
  issuerKeypair.publicKey(),
);
info

While anyone can create an asset, there may be real-world compliance implications relevant to your use case.

note

You’ll want to make sure you publish information about your asset to establish trust with your users and prevent errors. Learn how to do so with our Publish Information About Your Asset section.

Network transactions​

Build transaction to establish distributor trustline​

Accounts must establish a trustline with the issuing account to hold that issuer’s asset. This is true for all assets except for the network’s native token, Lumens.

note

If you’d like to avoid your users having to deal with trustlines or XLM, consider using sponsored reserves. Read more in our Sponsored Reserves Encyclopedia Entry.

const StellarSdk = require("stellar-sdk");
const server = new StellarSdk.Horizon.Server(
  "https://horizon-testnet.stellar.org",
);
const account = await server.loadAccount(distributorKeypair.publicKey());

// This step only builds the transaction.  It still needs to be signed.
const transaction = new StellarSdk.TransactionBuilder(account, {
  fee: StellarSdk.BASE_FEE,
  networkPassphrase: StellarSdk.Networks.TESTNET,
})
  // The `changeTrust` operation creates (or alters) a trustline
  .addOperation(
    StellarSdk.Operation.changeTrust({
      asset: astroDollar,
      limit: "1000", // optional
      source: distributorKeypair.publicKey(),
    }),
  )
  .setTimeout(100)
  .build();

Issuer payment to distributor​

Payments are the most popular operation to actually issue (or mint) your asset, compared to other issuances. A payment creates the amount of an asset specified, up to the maximum 64-bit integer. Relevantly, you do not need to scale up the issuing amount of your asset by the XDR minimum increment.

// We're using TransactionBuilder(...) as a short-hand here
// to show that these operations can be "chained" together.
const transaction = new StellarSdk.TransactionBuilder(...)
  // The `payment` operation sends the `amount` of the specified
  // `asset` to our distributor account
  .addOperation(StellarSdk.Operation.payment({
    destination: distributorKeypair.publicKey(),
    asset: astroDollar,
    amount: '1000',
    source: issuerKeypair.publicKey()
  }))
note

You can also create a market directly from the issuing account and issue tokens via trading.

Optional transactions​

Configure maximum supply​

danger

This section details how to lock your account with the purpose of limiting the supply of your issued asset. However, locking your account means you’ll never be able to do anything with it ever again—whether that’s adjusting signers, changing the home domain, claiming any held XLM, or any other operation. Your account will be completely frozen.

You can permanently configure the exact number of an asset that will ever exist. Learn more about asset supply in our section on Limiting the Supply of an Asset

const lockAccountTransaction = new StellarSdk.TransactionBuilder(...)
  // This `setOptions` operation locks the issuer account
  // so there can never be any more of the asset minted
  .addOperation(StellarSdk.Operation.setOptions({
    masterWeight: 0,
    source: issuerKeypair.publicKey()
  }))

Approve distributor trustline​

If you enable the authorization flag, the issuing account also needs to approve the distributor account's trustline request before the issuing payment. You will need to do this for all new accounts when set for your asset.

const issuingAccount = await server.loadAccount(issuerKeypair.publicKey());
const transaction = new StellarSdk.TransactionBuilder(...)
  .addOperation(
    StellarSdk.Operation.setTrustLineFlags({
      trustor: distributorKeypair.publicKey(),
      asset: astroDollar,
      flags: {
        authorized: true,
      },
    }),
  )
  .setTimeout(100)
  .build();

Full Code Sample​

var StellarSdk = require("stellar-sdk");
var server = new StellarSdk.Horizon.Server(
  "https://horizon-testnet.stellar.org",
);

// Keys for accounts to issue and receive the new asset
var issuerKeys = StellarSdk.Keypair.fromSecret(
  "SCZANGBA5YHTNYVVV4C3U252E2B6P6F5T3U6MM63WBSBZATAQI3EBTQ4",
);
var receivingKeys = StellarSdk.Keypair.fromSecret(
  "SDSAVCRE5JRAI7UFAVLE5IMIZRD6N6WOJUWKY4GFN34LOBEEUS4W2T2D",
);

// Create an object to represent the new asset
var astroDollar = new StellarSdk.Asset("AstroDollar", issuerKeys.publicKey());

// First, the receiving account must trust the asset
server
  .loadAccount(receivingKeys.publicKey())
  .then(function (receiver) {
    var transaction = new StellarSdk.TransactionBuilder(receiver, {
      fee: 100,
      networkPassphrase: StellarSdk.Networks.TESTNET,
    })
      // The `changeTrust` operation creates (or alters) a trustline
      // The `limit` parameter below is optional
      .addOperation(
        StellarSdk.Operation.changeTrust({
          asset: astroDollar,
          limit: "1000",
        }),
      )
      // setTimeout is required for a transaction
      .setTimeout(100)
      .build();
    transaction.sign(receivingKeys);
    return server.submitTransaction(transaction);
  })
  .then(console.log)

  // Second, the issuing account actually sends a payment using the asset
  .then(function () {
    return server.loadAccount(issuerKeys.publicKey());
  })
  .then(function (issuer) {
    var transaction = new StellarSdk.TransactionBuilder(issuer, {
      fee: 100,
      networkPassphrase: StellarSdk.Networks.TESTNET,
    })
      .addOperation(
        StellarSdk.Operation.payment({
          destination: receivingKeys.publicKey(),
          asset: astroDollar,
          amount: "10",
        }),
      )
      // setTimeout is required for a transaction
      .setTimeout(100)
      .build();
    transaction.sign(issuerKeys);
    return server.submitTransaction(transaction);
  })
  .then(console.log)
  .catch(function (error) {
    console.error("Error!", error);
  });