Skip to content
Arete Docs

Arete documentation

Integrate an existing protocol

For the complete documentation index optimized for AI agents, see llms.txt or llms-full.txt. A markdown version of this page is available by appending .md to the URL or sending Accept: text/markdown.

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /integrating-protocols/overview.md.

Install a published protocol to use its steps, state, and events in your app. An available public protocol already has a deployment: you do not deploy a copy into your account just to call it.

Find a callable package

Section titled “Find a callable package”
Terminal window
a4 protocol search
a4 protocol search "<intent>"
a4 protocol show <slug>
a4 explore protocol <package>

Listings describe callable Arete Protocols, including steps, access, trust, and the exact package reference to install. Search and show need no API key. Curated knowledge about external Solana protocols is a separate discovery surface; a knowledge entry does not imply an executable Arete Protocol exists.

Inspect the listing and package descriptor. Use the advertised install command and a supported target rather than assuming a particular example is public.

Install the client

Section titled “Install the client”
Terminal window
a4 init -y
a4 install protocol <package>@=<version> --ts

Use the exact package and version from discovery. The installer records the dependency in arete.toml, pins it in arete.lock, and generates the client plus its stack and program dependencies. Read the generated README.md for the import path, step signatures, access, and rejection codes.

Create a client

Section titled “Create a client”

This example uses placeholder names: replace the import with the generated module for your installed protocol.

import { createProtocolClient } from "@usearete/sdk";
import PROTOCOL from "./generated/typescript/protocols/my-protocol/my-protocol.js";


// Browser: an origin-bound publishable key from your account.
const client = createProtocolClient(PROTOCOL, {
  auth: { publishableKey },
});


const actions = await client.actions({ wallet });
const instances = await client.instances.list({ limit: 20 });

Use a secret-key client on your backend for secret steps. In a server or local script, omitting auth options uses the supported environment or CLI login credential resolution. The API still checks your account’s access. Never embed a secret key in a browser.

A public step permits preparation with a publishable-key session. It still requires its declared wallet authority to sign. create and role steps default to secret; inspect the installed step declarations.

Compose a session

Section titled “Compose a session”
import { createSession } from "@usearete/sdk";


const session = await createSession(
  { protocols: { myProtocol: PROTOCOL } },
  { auth: { publishableKey } },
);
const client = session.protocols.myProtocol;

The protocol’s dependencies are promoted into session.stacks and session.programs, alongside other installed dependencies. A standalone protocol client exposes stack definitions; a session supplies the connected stack clients. Use a session when the app needs live data as well as protocol API reads. Close the client or session when its owner is done with it. In React, AreteSessionProvider opens and closes it for you; see Compose a session in React.

Choose the next task

Section titled “Choose the next task”