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.
Illustrative example. The snippets on this page show how each message is built. They are not a tested project you can run as written. You supply the signer and every identifier. Build against a test network, never against mainnet.
Before you start
You need:
- An IXO account with enough
uixofor 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-sdkimport { 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
| Operation | Message | Effect |
|---|---|---|
| Cancel batches | MsgCancelToken | The owner cancels specific token batches and gives a reason. |
| Pause minting | MsgPauseToken | The minter halts further minting on a contract. paused: true halts it and false resumes it. |
| Stop the contract | MsgStopToken | The 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 see | What to do |
|---|---|
| invalid class DID | class must be a valid entity DID for an existing token protocol entity. Confirm that the entity exists and that you control it. |
| cap exceeded | MsgMintToken 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 stopped | Minting is refused on a paused contract and on a stopped one. Send MsgPauseToken with paused: false to resume. MsgStopToken cannot be reversed. |
| unauthorized credit transfer | A delegated MsgTransferCredit needs a WithdrawPaymentAuthorization that names the authorization_id you supplied. See Custom authorisations for IXO Claims. |