> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryvo.network/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> @ryvonetwork/sdk - install, quick start, and what is inside.

[`@ryvonetwork/sdk`](https://www.npmjs.com/package/@ryvonetwork/sdk) is the official TypeScript SDK for the Ryvo Protocol. It wraps the live Anchor program into a small set of typed helpers so you can integrate the protocol without hand-rolling IDLs, PDAs, or message encoders.

The SDK is developed in the open at [Ryvonetwork/ryvo-protocol-sdk](https://github.com/Ryvonetwork/ryvo-protocol-sdk).

## What is inside

The package exposes five composable layers:

| Layer                                          | What it gives you                                                                                                                                     |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`RyvoClient`](/sdk/client)                    | A thin, typed wrapper around the Anchor program with one method per instruction.                                                                      |
| [PDA helpers](/sdk/pdas)                       | Deterministic derivations for every account the program uses (`global-config`, `token-registry`, `participant`, `vault-token-account`, `channel-v2`). |
| [Message builders](/sdk/messages)              | `ryvo-cmt-v5` commitment and clearing-round message encoders, plus signing helpers.                                                                   |
| [Account helpers](/sdk/client#account-helpers) | Convenience readers for participant token balances and for computing the next commitment amount from a channel.                                       |
| Constants & IDL                                | `RYVO_PROTOCOL_PROGRAM_ID`, `RYVO_CHAIN_IDS`, seed strings, and the generated Anchor IDL.                                                             |

The SDK depends on `@coral-xyz/anchor`, `@solana/web3.js`, and `@noble/curves`, all standard in the Solana TypeScript ecosystem. It has no hidden RPC behavior: every call you make goes through the `AnchorProvider` you construct it with.

## Install

```bash theme={null}
npm install @ryvonetwork/sdk @coral-xyz/anchor @solana/web3.js
```

Requirements:

* Node.js `>= 18`
* An Anchor-compatible `AnchorProvider` (browser wallet adapter, backend keypair, test ledger, etc.)

The package is ESM-only (`"type": "module"`). In CommonJS codebases, use a dynamic `import()` or switch to ESM.

## Quick start

```ts theme={null}
import * as anchor from "@coral-xyz/anchor";
import { RyvoClient } from "@ryvonetwork/sdk";

const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);

const client = new RyvoClient({ provider });

const owner = provider.wallet.publicKey;
const participantPda = client.participantAddress(owner);
const participant = await client.fetchParticipant(owner);

console.log("Participant ID:", participant.participantId);
```

By default, `RyvoClient` uses the live program ID baked into the IDL (`3UyUFeNsUYPpM6hMRf7H8wg3MKEXQ82rqnsXhZrUwgSD` on devnet). To target a different deployment, pass a `programId` override:

```ts theme={null}
import { PublicKey } from "@solana/web3.js";

const client = new RyvoClient({
  provider,
  programId: new PublicKey("<your program id>"),
});
```

## Sign a commitment and settle

The following snippet is the full direct-settlement flow, compressed. See [Recipes](/sdk/recipes) for the expanded version with participant setup, deposits, and channel creation.

```ts theme={null}
import {
  RyvoClient,
  createCommitmentMessage,
  createEd25519Instruction,
  deriveMessageDomain,
  RYVO_CHAIN_IDS,
} from "@ryvonetwork/sdk";

const client = new RyvoClient({ provider });
const messageDomain = deriveMessageDomain(client.programId, RYVO_CHAIN_IDS.devnet);

const message = createCommitmentMessage({
  messageDomain,
  payerId: payer.participantId,
  payeeId: payee.participantId,
  tokenId: 2,
  committedAmount: 1_000_000n, // micro-USDC
});

const ed25519Ix = createEd25519Instruction(payerKeypair, message);

await client
  .settleIndividual({
    payerAccount: client.participantAddress(payerKeypair.publicKey),
    payeeAccount: client.participantAddress(payeeKeypair.publicKey),
    channelState: client.channelAddress(
      payer.participantId,
      payee.participantId,
      2,
    ),
    submitter: payeeKeypair.publicKey,
  })
  .preInstructions([ed25519Ix])
  .signers([payeeKeypair])
  .rpc();
```

Two things are worth noting:

1. The commitment is signed off-chain by the payer. The payee is the one who submits it on-chain.
2. `createEd25519Instruction` **must** be added to the same transaction as `settleIndividual`; Ryvo verifies it through the `instructions` sysvar.

## Versioning

The SDK is on the `0.2.x` line while the protocol surface stabilises. Breaking changes are signalled in the npm [changelog](https://github.com/Ryvonetwork/ryvo-protocol-sdk/releases) and tracked against the program's IDL. The package ships the generated IDL and TypeScript program type, so upgrading the SDK is always aligned with a protocol upgrade.

## Agentic tooling

If you are building agent workflows, pair the SDK with the agentic toolchain:

* protocol CLI for state inspection and unsigned action prep
* protocol MCP for tool-calling integrations
* gateway CLI and MCP for route discovery and payment flows
* reusable skills for Codex-style agent workflows

See [Agentic tools](/reference/agentic-tools) for package names, defaults, and workflow guidance.

## Where to go next

<CardGroup cols={2}>
  <Card title="RyvoClient" icon="code" href="/sdk/client">
    Every instruction the SDK can build, initialize, deposit, lock, settle, withdraw.
  </Card>

  <Card title="PDAs & constants" icon="key" href="/sdk/pdas">
    Derive every account the program uses, deterministically and off-chain.
  </Card>

  <Card title="Messages" icon="signature" href="/sdk/messages">
    Build `ryvo-cmt-v5` and cooperative-round messages.
  </Card>

  <Card title="Recipes" icon="book-open" href="/sdk/recipes">
    End-to-end flows: register, fund, sign, settle, withdraw.
  </Card>

  <Card title="Agentic tools" icon="robot" href="/reference/agentic-tools">
    Protocol CLI, MCP, skills, and LLM text built on the SDK.
  </Card>
</CardGroup>