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

# Manage smart accounts

> Add, remove, and toggle authenticators on IXO smart accounts to extend Cosmos SDK signing with conditional rules.

The IXO `smartaccount` module replaces the default Cosmos SDK signature ante handler with an opt-in pluggable system. Each account can register one or more **authenticators** — signature verifiers, message filters, spend-limit contracts, or composite logic — that execute on every transaction the account opts in to. If no authenticators are selected, transactions fall back to the standard Cosmos SDK signature flow.

## Before you start

You need:

* An IXO account with `uixo` for fees on the network you target — see [Networks and endpoints](/reference/networks-and-endpoints).
* An offline signer — see the [SDK README](https://github.com/ixofoundation/ixo-multiclient-sdk#creating-signers).
* An authenticator type and config payload to register. The supported types are defined in the [smartaccount types proto](https://github.com/ixofoundation/ixo-blockchain/tree/main/proto/ixo/smartaccount/v1beta1).

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

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

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

## Add an authenticator

```ts theme={null}
const addAuthenticatorMsg = {
  typeUrl: "/ixo.smartaccount.v1beta1.MsgAddAuthenticator",
  value: ixo.smartaccount.v1beta1.MsgAddAuthenticator.fromPartial({
    sender: signerAddress,
    authenticatorType: "SignatureVerification",
    data: new TextEncoder().encode(JSON.stringify({ pubkey: pubkeyHex })),
  }),
};

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

The chain assigns an `id` to each authenticator on success. Read it from transaction events to reference the authenticator in subsequent transactions.

## Remove an authenticator

```ts theme={null}
const removeAuthenticatorMsg = {
  typeUrl: "/ixo.smartaccount.v1beta1.MsgRemoveAuthenticator",
  value: ixo.smartaccount.v1beta1.MsgRemoveAuthenticator.fromPartial({
    sender: signerAddress,
    id: 1n,
  }),
};
```

## Pause the module (governance)

`MsgSetActiveState` is the circuit breaker — only the module's gov authority can broadcast it.

```ts theme={null}
const setActiveMsg = ixo.smartaccount.v1beta1.MsgSetActiveState.fromPartial({
  authority: govAuthority,
  active: false,
});
```

When `active` is `false`, the smart-account ante handler is skipped and all transactions use the default Cosmos SDK signature path.

## Use authenticators on a transaction

A transaction opts in to specific authenticators via the **`AuthenticatorTxExtension`** TX extension. The full pattern depends on your signing flow — see the [smartaccount module README](https://github.com/ixofoundation/ixo-blockchain/tree/main/x/smartaccount) and the [README for the IXO MultiClient SDK](https://github.com/ixofoundation/ixo-multiclient-sdk) for current helpers. The extension carries the list of authenticator IDs to use for each signer.

## Composite authenticators

Composite authenticators combine sub-authenticators using boolean logic.

<AccordionGroup>
  <Accordion title="AllOf" icon="link">
    Approves only when every sub-authenticator approves: `auth(a) && auth(b) && ...`.
  </Accordion>

  <Accordion title="AnyOf" icon="code-branch">
    Approves when at least one sub-authenticator approves: `auth(a) || auth(b) || ...`.
  </Accordion>

  <Accordion title="PartitionedAllOf" icon="user-group">
    Multi-signature where signatures are split across sub-authenticators (one signer per sub-authenticator).
  </Accordion>
</AccordionGroup>

Example shapes:

```text theme={null}
// One-click trading: hot key restricted to swap messages with on-chain spend-limit guard
AllOf(
  SignatureVerification(usersPubKey),
  AnyOf(
    MessageFilter(SwapMsg1),
    MessageFilter(SwapMsg2)
  ),
  CosmwasmAuthenticator(spendLimitContract, params)
)

// Multisig (2-of-3): each signer satisfies one branch
PartitionedAllOf(pubkey1, pubkey2, pubkey3)

// Cosigner protection: cosigner approves alongside a user-selected set
AllOf(
  SignatureVerification(cosignerPubKey),
  AnyOf(...userAuthenticators)
)
```

## Authentication phases

Each authenticator runs through a three-phase lifecycle on every transaction:

1. **Authenticate** — verify the transaction is authorized.
2. **Track** — record any state changes the authenticator needs (committed regardless of transaction outcome).
3. **Confirm execution** — validate the post-execution effects.

## Verify the result

Query an account's authenticators through the `ixo.smartaccount.v1beta1.Query/AccountAuthenticators` endpoint on the [gRPC gateway API](/api-reference/grpc-gateway-api). Module params (including `is_smart_account_active`) are read from `Query/Params`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="unknown authenticator type" icon="circle-xmark">
    `authenticatorType` must match one of the registered types in the chain's `smartaccount` module. Check `Query/Params.maximum_unauthenticated_gas` and the module's registered types.
  </Accordion>

  <Accordion title="authenticator id not found" icon="binoculars">
    `MsgRemoveAuthenticator` fails when `id` does not exist for `sender`. Query `AccountAuthenticators` to confirm the id.
  </Accordion>

  <Accordion title="module inactive" icon="pause">
    When `is_smart_account_active` is `false`, `MsgAddAuthenticator` and `MsgRemoveAuthenticator` are rejected. The module is gated by gov via `MsgSetActiveState`.
  </Accordion>

  <Accordion title="signature verification failed" icon="key">
    Ensure the TX extension lists the correct authenticator IDs in the order matching the signer set, and that the data payload registered with `MsgAddAuthenticator` is the canonical encoding for that authenticator type.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="IXO MultiClient SDK" icon="server" href="/sdk-reference/multiclient-sdk">
    Module-level features and types.
  </Card>

  <Card title="Smart account proto" icon="github" href="https://github.com/ixofoundation/ixo-blockchain/tree/main/proto/ixo/smartaccount/v1beta1">
    Source of truth for smart-account messages.
  </Card>

  <Card title="Session keys" icon="key" href="/guides/dev/session-keys">
    Issue scoped session keys backed by smart-account authenticators.
  </Card>

  <Card title="Manage authorization" icon="user-shield" href="/guides/dev/authz">
    Use Cosmos authz alongside smart-account authenticators.
  </Card>
</CardGroup>