Developer workflows

These workflows show the canonical message patterns from the @ixo/impactxclient-sdk README. For full type definitions, see @ixo/impactxclient-sdk and the proto definitions.

Prerequisites

1. Install dependencies: @ixo/impactxclient-sdk. For Agentic Oracle integration, see Agentic Oracles ADK.
2. Choose RPC endpoint and chain ID from Networks and endpoints.
3. Choose auth for each surface from Authentication matrix. On-chain writes require a funded signer (wallet or key management you control).

npm install @ixo/impactxclient-sdk

1. Initialize query and signing clients

Reads use createQueryClient. Writes need a signer-backed createSigningClient. Both target the same RPC endpoint.

import {
  ixo,
  createQueryClient,
  createSigningClient,
} from "@ixo/impactxclient-sdk";

const RPC_ENDPOINT = "https://rpc.ixo.world";

const queryClient = await createQueryClient(RPC_ENDPOINT);
const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);

Errors: RPC misconfiguration surfaces as connection timeouts or JSON-RPC errors. Try a different node if your operator allows; confirm TLS and chainId against the network row in Networks and endpoints.

For signer setup (Cosmos-kit, Keplr, or getOfflineSigner from cosmjs-utils), see SDK README — Creating signers.

2. Register an entity (digital twin)

Compose MsgCreateEntity, sign and broadcast.

const createEntityMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgCreateEntity",
  value: ixo.entity.v1beta1.MsgCreateEntity.fromPartial({
    ownerAddress: signerAddress,
    entityType: "asset",
    context: [
      ixo.iid.v1beta1.Context.fromPartial({
        key: "class",
        val: "did:ixo:entity:protocol123",
      }),
    ],
    verification: [],
    controller: [],
    service: [],
    linkedResource: [],
    accordedRight: [],
    linkedEntity: [],
    linkedClaim: [],
  }),
};

const response = await signingClient.signAndBroadcast(
  signerAddress,
  [createEntityMsg],
  "auto",
);

Read the resulting entity through the query client:

const entities = await queryClient.ixo.entity.v1beta1.entityList();

Errors: invalid entityType or context key/value pairs that the chain does not accept return failed transactions. Inspect code and rawLog on the broadcast response.

3. Submit a claim

const submitClaimMsg = {
  typeUrl: "/ixo.claims.v1beta1.MsgSubmitClaim",
  value: ixo.claims.v1beta1.MsgSubmitClaim.fromPartial({
    creator: signerAddress,
    claimId: "bafkreih...",
    collectionId: "12",
    adminAddress: collectionAdminAddress,
  }),
};

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

Errors: missing collectionId, schema mismatch, or insufficient authorization produce chain errors. Cross-check Claims management and Custom authorisations for IXO Claims.

4. Evaluate a claim (oracle-assisted)

An Agentic Oracle returns a determination off-chain; the on-chain record is written by MsgEvaluateClaim. The example below assumes an Agentic Oracle service exposes a verify endpoint your code calls — see Agentic Oracles ADK for the canonical SDK home and Build agentic oracles for the architecture.

const verification = await callOracleVerify({
  oracleEndpoint: "https://oracle.example",
  claimId: "bafkreih...",
});

const evaluateMsg = {
  typeUrl: "/ixo.claims.v1beta1.MsgEvaluateClaim",
  value: ixo.claims.v1beta1.MsgEvaluateClaim.fromPartial({
    creator: signerAddress,
    claimId: "bafkreih...",
    collectionId: "12",
    oracle: oracleAddress,
    adminAddress: collectionAdminAddress,
    status: 1,
    reason: 0,
    verificationProof: verification.proofCid,
    amount: [],
  }),
};

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

Errors: oracle 401/403 typically means wrong operator credential or DID. Chain-side MsgEvaluateClaim failures usually point to authorization (no EvaluateClaimAuthorization) or claim state.

5. Issue tokens against an evaluated claim

After approval, mint tokens with MsgMintToken against your token contract — see Manage tokens for the full message family.

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

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

6. Verifiable credentials

Credential issuance and verification are governed by your program's issuer keys, schemas, and registry or IXO Matrix storage — see Credential issuance and Identity and credentials. Implement issuance in the component that holds the issuer key; verifiers should check signature, issuer DID, schema, and revocation/status lists. For HTTP-oriented credential flows on Emerging, see Emerging API and the matching auth rules in Authentication matrix.

Error handling

• HTTP service calls: use Error handling for status codes; add retry/backoff for 429 and transient 5xx.
• GraphQL (Blocksync): partial errors may appear in a top-level errors array while data is non-null — always check both. Unauthenticated introspection may be disabled on some deployments.
• DID resolution: if resolution fails, confirm the DID is registered on the expected network and that you query the correct registry or indexer endpoint.

Next steps