Skip to main content

Support on-chain transaction references in your app built with XMTP

Status Status

This package provides an XMTP content type to support on-chain transaction references. It is a reference to an on-chain transaction sent as a message. This content type facilitates sharing transaction hashes or IDs, thereby providing a direct link to on-chain activities. Transaction references serve to display transaction details, facilitating the sharing of on-chain activities, such as token transfers, between users.

Open for feedback

You're welcome to provide feedback by commenting on XIP-21: On-chain transaction reference content type.

Configure the content type

In the JavaScript SDK, you need to import this package first.

npm i @xmtp/content-type-transaction-reference

After importing the package, you can register the codec.

import {
} from "@xmtp/content-type-transaction-reference";
// Create the XMTP client
const xmtp = await Client.create(signer, { env: "dev" });
xmtp.registerCodec(new TransactionReferenceCodec());

Send a transaction reference

With XMTP, a transaction reference is represented as an object with the following keys:

With XMTP, a transaction reference is represented as an object with the following keys:

const transactionReference: TransactionReference = {
* Optional namespace for the networkId
namespace: "eip155";
* The networkId for the transaction, in decimal or hexidecimal format
networkId: 1;
* The transaction hash
reference: "";
* Optional metadata object
metadata: {
transactionType: "transfer",
currency: "USDC",
amount: 100000, // In integer format, this represents 1 USDC (100000/10^6)
decimals: 6, // Specifies that the currency uses 6 decimal places
fromAddress: "0x456...def",
toAddress: "0x789...ghi"

Once you have a transaction reference, you can send it as part of your conversation:

await conversation.messages.send(transactionReference, {
contentType: ContentTypeTransactionReference,

Receive a transaction reference

To receive and process a transaction reference:

// Assume `loadLastMessage` is a thing you have
const message: DecodedMessage = await loadLastMessage();

if (!message.contentType.sameAs(ContentTypeTransactionReference)) {
// Handle non-transaction reference message

const transactionRef: TransactionReference = message.content;
// Process the transaction reference here

To handle unsupported content types, refer to the fallback section.

Display the transaction reference

Displaying a transaction reference typically involves rendering details such as the transaction hash, network ID, and any relevant metadata. Because the exact UI representation can vary based on your app's design, you might want to fetch on-chain data before showing it to the user.

Was the information on this page helpful?
powered by XMTP