Manage tokens

Create, mint, transfer, retire and pause IXO Protocol tokens with the IXO MultiClient SDK, then query a token's state. The code is illustrative.

The token module of the IXO Protocol issues tokens for verified outcomes, such as carbon offset units. This guide shows the messages that create a token, mint it, transfer it, retire it, mark it as transferred to another registry, and pause or stop it, using the IXO MultiClient SDK (@ixo/impactxclient-sdk).

The module wraps the ixo1155 smart contract, a CosmWasm implementation of the EIP-1155 multi-token standard. Each token has a token class (the DID of a token protocol entity) and a fixed cap. One contract holds both fungible and non-fungible balances. For the data model and the contract details, read the x/token proto definitions and the @ixo/impactxclient-sdk README.

Before you start

You need:

  • An IXO account with enough uixo for fees on the network you target. See Networks and endpoints.
  • An offline signer. See Creating signers in the SDK README.
  • The DID of the token protocol entity, which is the value you use as class. The chain checks the class against an existing entity.
  • To mint, a deployed token contract address, set by MsgCreateToken.
  • To transfer credit on behalf of another account, a valid WithdrawPaymentAuthorization. See Custom authorisations for IXO Claims.
npm install @ixo/impactxclient-sdk
import { ixo, createSigningClient } from "@ixo/impactxclient-sdk";

const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);

Create a token

MsgCreateToken registers a new token name under a token protocol entity. A cap of "0" means the supply is unlimited.

const createMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgCreateToken",
  value: ixo.token.v1beta1.MsgCreateToken.fromPartial({
    minter: signerAddress,
    class: "did:ixo:entity:protocol123",
    name: "CARBON",
    description: "Verified carbon offset units",
    image: "ipfs://bafy.../image.png",
    tokenType: "ixo1155",
    cap: "1000000",
  }),
};

await signingClient.signAndBroadcast(signerAddress, [createMsg], "auto");

Mint tokens

MsgMintToken issues new units in batches against an existing token contract. Each batch names a unique index and a collection DID.

const mintMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgMintToken",
  value: ixo.token.v1beta1.MsgMintToken.fromPartial({
    minter: signerAddress,
    contractAddress: tokenContractAddress,
    owner: ownerAddress,
    mintBatch: [
      ixo.token.v1beta1.MintBatch.fromPartial({
        name: "CARBON",
        index: "bafkreih...",
        amount: "1000",
        collection: "did:ixo:entity:collection456",
        tokenData: [],
      }),
    ],
  }),
};

await signingClient.signAndBroadcast(signerAddress, [mintMsg], "auto");

Transfer tokens

MsgTransferToken moves balances between accounts. Every token in one message must belong to the same contract.

const transferMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgTransferToken",
  value: ixo.token.v1beta1.MsgTransferToken.fromPartial({
    owner: signerAddress,
    recipient: recipientAddress,
    tokens: [
      ixo.token.v1beta1.TokenBatch.fromPartial({
        id: "bafkreih...",
        amount: "100",
      }),
    ],
  }),
};

await signingClient.signAndBroadcast(signerAddress, [transferMsg], "auto");

Retire tokens

MsgRetireToken removes tokens from circulation for good and keeps their history on chain. Use it for end claims such as voluntary carbon retirement.

const retireMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgRetireToken",
  value: ixo.token.v1beta1.MsgRetireToken.fromPartial({
    owner: signerAddress,
    tokens: [
      ixo.token.v1beta1.TokenBatch.fromPartial({
        id: "bafkreih...",
        amount: "50",
      }),
    ],
    jurisdiction: "ZA-WC-7700",
    reason: "Voluntary retirement on behalf of buyer X",
  }),
};

The jurisdiction field has the format <country-code>[-<sub-national-code>[-<postal-code>]]. Only the country code is required.

Transfer credit (ITMO state change)

MsgTransferCredit sets tokens to a "transferred" state when the units move off the protocol to a different registry. An example is Internationally Transferred Mitigation Outcomes (ITMOs) under Article 6.2 of the Paris Agreement. The message takes an optional authorization_id for delegated transfers.

const creditTransferMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgTransferCredit",
  value: ixo.token.v1beta1.MsgTransferCredit.fromPartial({
    owner: signerAddress,
    tokens: [
      ixo.token.v1beta1.TokenBatch.fromPartial({
        id: "bafkreih...",
        amount: "100",
      }),
    ],
    jurisdiction: "CH",
    reason: "ITMO transfer to Swiss national registry",
    authorizationId: "auth-2025-001",
  }),
};

Cancel, pause, or stop a token

OperationMessageEffect
Cancel batchesMsgCancelTokenThe owner cancels specific token batches and gives a reason.
Pause mintingMsgPauseTokenThe minter halts further minting on a contract. paused: true halts it and false resumes it.
Stop the contractMsgStopTokenThe minter stops the token contract for good. This cannot be reversed.
const pauseMsg = {
  typeUrl: "/ixo.token.v1beta1.MsgPauseToken",
  value: ixo.token.v1beta1.MsgPauseToken.fromPartial({
    minter: signerAddress,
    contractAddress: tokenContractAddress,
    paused: true,
  }),
};

Check the result

Query the token's state through the Blocksync GraphQL API:

query Token($id: String!) {
  token(id: $id) {
    id
    name
    description
    cap
    class
    minter
    minted
    transferred
    retired
    cancelled
  }
}

You can also read from the token contract directly. The gRPC gateway API lists the endpoints.

When something goes wrong

What you seeWhat to do
invalid class DIDclass must be a valid entity DID for an existing token protocol entity. Confirm that the entity exists and that you control it.
cap exceededMsgMintToken fails if the new total would exceed the token's cap. Raise the cap by creating the token again, or split issuance across more token names.
contract paused or stoppedMinting is refused on a paused contract and on a stopped one. Send MsgPauseToken with paused: false to resume. MsgStopToken cannot be reversed.
unauthorized credit transferA delegated MsgTransferCredit needs a WithdrawPaymentAuthorization that names the authorization_id you supplied. See Custom authorisations for IXO Claims.

Next steps