---
title: "Protocol API and authoring reference"
description: "Find protocol authoring entry points, generated client methods, React hooks, build commands, and cross-language interfaces."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

> For the complete documentation index optimized for AI agents, see [llms.txt](https://docs.arete.run/llms.txt) or [llms-full.txt](https://docs.arete.run/llms-full.txt). A markdown version of this page is available at [/reference/protocols.md](https://docs.arete.run/reference/protocols.md) or by sending `Accept: text/markdown`.
Use this page to locate protocol interfaces after following the
[authoring](/building-protocols/definition/) or
[integration](/integrating-protocols/overview/) guide. Exact installed types
and the generated README describe the release your application actually calls.

## Authoring package

`@usearete/protocol` exports `defineProtocol`, `ix`, and `builtins` for
protocol definitions; `wirePreparedOperation`, `PrepareInputV1`, and
`ProtocolContextV1` for handlers; and validators and types for public artifacts.
`@usearete/protocol/testing` supplies `runHandler` and replay contexts.

Definition fields include `programs`, `stacks`, `params`, `resources`, `roles`,
`reads`, `machines`, `steps`, `metadata`, `reactions`, `events`, and `stack`.
Use the package's TypeScript declarations for each nested schema and
[the package reference](https://github.com/AreteA4/arete/tree/main/typescript/protocol).
Do not copy identity hashes from a sample instead of importing installed modules.

`builtins(...)` returns typed modules for the builtin programs, and `ix`
checks their instructions like an installed program's. Each builtin has one
name: `system`, `splToken`, `associatedToken`, `computeBudget` and `memo`.
Other names are errors that name the builtin: `spl-ata` and `splAta` are
`associatedToken`, `spl-token` is `splToken`, `system-program` is `system`,
`spl-memo` is `memo` and `compute-budget` is `computeBudget`.

```ts
const { associatedToken } = builtins("associatedToken");
ix(associatedToken, "createIdempotent", { accounts: { fundingAddress: "wallet" /* … */ } });
```

SPL Token's `owner` and `authority` accounts are signers, so pass a key the
step signs with, such as `wallet` or an ephemeral key. Templates cannot use a
multisig token authority: its members would sign as remaining accounts, and
remaining accounts never sign.

```sh
npx arete-protocol check [protocol.ts]
npx arete-protocol build [protocol.ts] --out .arete/protocol
```

Brackets indicate optional arguments, not literal shell syntax. `--server-release`
selects server release derivation when needed for comparing release identities.

`check` runs local checks for syntax and names. With a secret key in
`ARETE_API_KEY`, it also runs Arete's own upload checks (expression types,
and templates against their pinned program specs) without uploading
anything. It prints each rejection's spec path, message and code. Pass
`--remote` to require the server check, or `--offline` to skip it.
`a4 protocol deploy --dry-run` runs the same server check with your `a4`
login, and so does the MCP tool `protocol_check`.
Normal development uses `a4 dev up`; production uses `a4 protocol deploy`.

## TypeScript protocol client

`createProtocolClient(definition, options)` creates a standalone client.
`createSession({ protocols: { alias: definition } }, options)` includes it in
an application session.

| Surface                                                  | Purpose                                                          |
| -------------------------------------------------------- | ---------------------------------------------------------------- |
| `steps.<name>.prepare(input, options?)`                  | Prepare a typed step or return a typed rejection                 |
| `actions({ wallet, instance?, cursor?, limit? })`        | Wallet actions and related instances                             |
| `allowedSteps({ instance, wallet })`                     | Step availability for one instance                               |
| `instances.list(filter?)`, `instances.get(id, options?)` | Canonical instance reads                                         |
| `instances.forWallet(wallet, { relation? })`             | Every instance a wallet relates to, across pages of `actions`    |
| `instances.use(id, options?)`                            | Reactive instance handle with optional live row                  |
| `participants.get({ instance, wallet })`                 | Canonical participant read                                       |
| `submit(intent, signedTransactions)`                     | Submit exact wallet-signed transactions                          |
| `intents.get(executionId)`                               | Read execution outcome                                           |
| `events(instanceId, options)`                            | Resumable instance event stream                                  |
| `metadata.instance(id)`, `metadata.participant(input)`   | Metadata handles and wallet proof messages                       |
| `squads.proposer()`, `status(multisig)`                  | The Squads proposer and whether it is an Initiate-only member    |
| `getReceipt(signature)`, `getReceiptKeys()`              | Receipt and verification keys                                    |
| `stacks`, `programs`                                     | Included definitions, or connected dependencies inside a session |
| `close()`                                                | Release the client's owned resources                             |

The account's Squads multisigs are set up on the dashboard or with
`a4 squads`; code that creates a multisig or adds the proposer uses the Squads
v4 program SDK's Arete setup helpers. See [Squads](/building-protocols/squads/).

Secret-key clients expose client-callable steps; publishable-key clients are
typed for public steps. Runtime access and authority checks still apply.
Amounts use `ProtocolInteger` decimal strings. Prepare returns the discriminated
`ProtocolPrepareResult`: check `ok` before reading `intent` and `transactions`.

## React hooks

| Hook                                              | Purpose                                                        |
| ------------------------------------------------- | -------------------------------------------------------------- |
| `useProtocolInstance(client, id, options?)`       | Canonical instance, optional live row, loading, error, refresh |
| `useWalletActions(client, input, options?)`       | Wallet action discovery                                        |
| `useAllowedSteps(client, input, options?)`        | Availability for one instance and wallet                       |
| `useProtocolParticipant(client, input, options?)` | Participant state                                              |
| `useProtocolEvents(client, id, options)`          | Event subscription with unmount cleanup                        |

[React integration](/integrating-protocols/react/) explains stable client
ownership and event-driven refresh.

## Rust and Python

Install verified targets with `a4 install protocol <package> --rust` or
`--python`. Generated clients expose the same concepts with language-specific
names and typed step arguments. Read their generated README for construction,
imports, steps, rejection types, and event payloads.

Wallet action discovery uses `actions` in each language. A wallet's
instances across every page are `instances_for_wallet(wallet, relation)` in
Rust (`Option<&str>`) and `instances_for_wallet(wallet, relation=...)` in
Python. Receipt helpers use
`verify_receipt` and `verify_receipt_on_chain` in Rust and Python.
Python's repository implementation is available for development; check its
[publication status](/sdks/python/) before selecting it for distribution.

## CLI and MCP

[Protocol CLI commands](/cli/commands/#a4-protocol-init-dir) cover init, deploy,
actions, search, show, and listing requests.
[Dev commands](/cli/local-development/) cover environments, wallets, steps,
streaming, replay, and debugging.
[Protocol MCP tools](/agent-skills/protocols/) cover discovery, actions,
prepare, submit, intent tracking, and receipts, with an optional local signer.