> ## Documentation Index
> Fetch the complete documentation index at: https://ixoworld-mintlify-9a7944b6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage entities

> Create, transfer, verify, and govern entity domains on the IXO Protocol with the IXO MultiClient SDK.

This guide shows the chain-level message patterns for managing **entities** on the IXO Protocol using the [`@ixo/impactxclient-sdk`](https://www.npmjs.com/package/@ixo/impactxclient-sdk). For the data model, read [Entity domains](/guides/dev/ixo-domains) and [Domain configuration](/articles/domain-config) first.

## Before you start

You need:

* A funded IXO account on the network you target — see [Networks and endpoints](/reference/networks-and-endpoints).
* An offline signer (Cosmos-kit, Keplr, or `getOfflineSigner` from `cosmjs-utils`) — see the [SDK README on creating signers](https://github.com/ixofoundation/ixo-multiclient-sdk#creating-signers).
* The [`@ixo/impactxclient-sdk`](https://www.npmjs.com/package/@ixo/impactxclient-sdk) installed.

```bash theme={null}
npm install @ixo/impactxclient-sdk
```

The signing client follows the canonical three-step pattern: compose, sign, broadcast.

```ts theme={null}
import { ixo, createSigningClient } from "@ixo/impactxclient-sdk";

const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);
```

## Create an entity

```ts theme={null}
const message = {
  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, [message], "auto");
```

The chain returns a transaction with events that include the new entity DID.

<Note>
  Field names mirror the [`x/entity` proto definitions](https://github.com/ixofoundation/ixo-blockchain/tree/main/proto/ixo/entity/v1beta1). Inspect `entity.proto` for the authoritative field list and any version-specific changes.
</Note>

## Transfer entity ownership

`MsgTransferEntity` reassigns the underlying entity NFT to a new controller account.

```ts theme={null}
const transferMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgTransferEntity",
  value: ixo.entity.v1beta1.MsgTransferEntity.fromPartial({
    id: entityDid,
    ownerAddress: currentOwnerAddress,
    recipientDid: "did:ixo:recipient123",
  }),
};

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

## Update verification status

A verifying authority (oracle, registry, or DAO controller) calls `MsgUpdateEntityVerified` to flip the verified flag for one or more entities it is permitted to attest.

```ts theme={null}
const verifyMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgUpdateEntityVerified",
  value: ixo.entity.v1beta1.MsgUpdateEntityVerified.fromPartial({
    id: entityDid,
    relayerNode: relayerDid,
    entityVerified: true,
  }),
};

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

## Manage entity accounts

Entities can hold named sub-accounts (for example `treasury`, `payouts`, `operations`) that can transact on behalf of the entity under explicit authz grants.

```ts theme={null}
const createAccountMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgCreateEntityAccount",
  value: ixo.entity.v1beta1.MsgCreateEntityAccount.fromPartial({
    id: entityDid,
    ownerAddress: signerAddress,
    name: "treasury",
  }),
};

const grantMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgGrantEntityAccountAuthz",
  value: ixo.entity.v1beta1.MsgGrantEntityAccountAuthz.fromPartial({
    id: entityDid,
    ownerAddress: signerAddress,
    name: "treasury",
    granteeAddress: granteeAddress,
    grant: /* cosmos.authz.v1beta1.Grant */ undefined,
  }),
};

const revokeMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgRevokeEntityAccountAuthz",
  value: ixo.entity.v1beta1.MsgRevokeEntityAccountAuthz.fromPartial({
    id: entityDid,
    ownerAddress: signerAddress,
    name: "treasury",
    granteeAddress: granteeAddress,
    msgTypeUrl: "/cosmos.bank.v1beta1.MsgSend",
  }),
};
```

Construct the `grant` value using `cosmos.authz.v1beta1.Grant.fromPartial({...})` with the matching authorization. See [Authentication and authorization](/guides/dev/authentication) and [Custom authorisations for IXO Claims](/guides/dev/authz-custom).

## Verify the result

Query the entity through the [Blocksync GraphQL API](/api-reference/blocksync-graphql-api):

```graphql theme={null}
query GetEntity($did: String!) {
  entity(id: $did) {
    id
    type
    status
    relayerNode
    owner
    controller
    accounts {
      name
      address
    }
  }
}
```

Or use the gRPC gateway directly — see [gRPC gateway API](/api-reference/grpc-gateway-api) for the entity module endpoints.

## Troubleshooting

<AccordionGroup>
  <Accordion title="invalid entity type" icon="circle-xmark">
    The `entityType` value must match a type the chain accepts. Inspect module params via the gRPC gateway or query the `EntityList` endpoint to confirm allowed types on your network.
  </Accordion>

  <Accordion title="unauthorized" icon="lock">
    The signer must be a current controller or relayer with the right capability. Confirm the signer address is in the entity's controller set or has an active authz grant.
  </Accordion>

  <Accordion title="account already exists" icon="user-xmark">
    Account names are unique per entity. Pick a different name or revoke and re-grant authz on the existing account.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configure domain settings" icon="sliders" href="/guides/dev/domain-settings">
    Update controllers, services, resources, and accorded rights.
  </Card>

  <Card title="Domain privacy patterns" icon="lock" href="/guides/dev/domain-privacy">
    Decide what to keep on protocol vs in IXO Matrix.
  </Card>

  <Card title="IXO MultiClient SDK" icon="server" href="/sdk-reference/multiclient-sdk">
    Full SDK reference and module list.
  </Card>

  <Card title="Entity proto definitions" icon="github" href="https://github.com/ixofoundation/ixo-blockchain/tree/main/proto/ixo/entity/v1beta1">
    Source of truth for message shapes.
  </Card>
</CardGroup>