Skip to main content
This guide shows the smallest useful Agon integration: one payer, one payee, one token, one payment channel, and one settled agon-cmt-v5 message. The examples mirror the current protocol tests. Until a dedicated SDK ships, this is the most direct way to integrate Agon today.

​
What you will build

By the end of this guide, you will have:
  1. Two registered participants.
  2. One funded payer.
  3. One open payment channel.
  4. One signed unilateral commitment.
  5. One successful direct settlement.

​
Prerequisites

  • Anchor workspace wired to the Agon program at Ba2puU8D2CLD1dYfRQ4YBXxirdyz3zVLLChvMf9AqJ1Y on devnet
  • Two keypairs with a small amount of SOL on devnet
  • One allowlisted settlement token (the default is aUSDC, token_id = 2)

​
1. Create the program client

import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { Ed25519Program, PublicKey, SystemProgram } from "@solana/web3.js";
import { AgonProtocol } from "../target/types/agon_protocol";

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

const program = anchor.workspace.agonProtocol as Program<AgonProtocol>;

​
2. Derive the PDAs

You will use the same PDA scheme throughout V4, so define these helpers once: 
const findParticipantPda = (owner: PublicKey) =>
  PublicKey.findProgramAddressSync(
    [Buffer.from("participant"), owner.toBytes()],
    program.programId
  )[0];

const findTokenRegistryPda = () =>
  PublicKey.findProgramAddressSync(
    [Buffer.from("token-registry")],
    program.programId
  )[0];

const findVaultTokenAccountPda = (tokenId: number) =>
  PublicKey.findProgramAddressSync(
    [
      Buffer.from("vault-token-account"),
      new anchor.BN(tokenId).toArrayLike(Buffer, "le", 2),
    ],
    program.programId
  )[0];

const findChannelPda = (payerId: number, payeeId: number, tokenId: number) =>
  PublicKey.findProgramAddressSync(
    [
      Buffer.from("channel-v2"),
      new Uint8Array(new Uint32Array([payerId]).buffer),
      new Uint8Array(new Uint32Array([payeeId]).buffer),
      new Uint8Array(new Uint16Array([tokenId]).buffer),
    ],
    program.programId
  )[0];
The channel PDA seed order is payer_id (u32 LE) || payee_id (u32 LE) || token_id (u16 LE) under the channel-v2 prefix. If you derive in a different order, settle_* instructions will reject the account.

​
3. Register both wallets

Each wallet registers once and keeps the same participant_id for the life of the deployment. 
await program.methods
  .initializeParticipant()
  .accounts({
    owner: alice.publicKey,
    feeRecipient,
  } as any)
  .signers([alice])
  .rpc();

await program.methods
  .initializeParticipant()
  .accounts({
    owner: bob.publicKey,
    feeRecipient,
  } as any)
  .signers([bob])
  .rpc();

const aliceParticipantPda = findParticipantPda(alice.publicKey);
const bobParticipantPda = findParticipantPda(bob.publicKey);

const aliceParticipant = await program.account.participantAccount.fetch(
  aliceParticipantPda
);
const bobParticipant = await program.account.participantAccount.fetch(
  bobParticipantPda
);
Read the assigned participant IDs: 
console.log(aliceParticipant.participantId);
console.log(bobParticipant.participantId);

​
4. Deposit the settlement token

Agon only settles allowlisted tokens. Once the payer has a normal SPL token account, deposit from that account into the protocol vault: 
await program.methods
  .deposit(tokenId, new anchor.BN(amount))
  .accounts({
    owner: alice.publicKey,
    participantAccount: aliceParticipantPda,
    ownerTokenAccount: aliceTokenAccount,
    vaultTokenAccount: findVaultTokenAccountPda(tokenId),
  } as any)
  .signers([alice])
  .rpc();
This moves tokens from the payer’s token account into the protocol vault and credits the payer’s available_balance.

​
5. Create the channel

One one-way payment channel exists for each payer_id + payee_id + token_id relationship. Channels are permanent. 
const channelPda = findChannelPda(
  aliceParticipant.participantId,
  bobParticipant.participantId,
  tokenId
);

await program.methods
  .createChannel(tokenId, null)
  .accounts({
    tokenRegistry: findTokenRegistryPda(),
    owner: alice.publicKey,
    payerAccount: aliceParticipantPda,
    payeeAccount: bobParticipantPda,
    payeeOwner: bob.publicKey,
    channelState: channelPda,
    systemProgram: SystemProgram.programId,
  } as any)
  .signers([alice, bob])
  .rpc();
The payeeOwner signer is only required when the payee’s inbound-channel policy demands consent. Under Permissionless, channel creation does not require the payee to sign.

​
6. Optionally lock funds

Locked funds are optional. Use them when the payee wants guaranteed payment capacity on the channel. 
await program.methods
  .lockChannelFunds(tokenId, new anchor.BN(1_000_000))
  .accounts({
    owner: alice.publicKey,
    payerAccount: aliceParticipantPda,
    payeeAccount: bobParticipantPda,
    channelState: channelPda,
  } as any)
  .signers([alice])
  .rpc();
Settlement spends locked balance first, then shared participant balance.

​
7. Build the agon-cmt-v5 message

agon-cmt-v5 is cumulative. It does not say “pay 25 again.” It says “this channel is now authorized up to cumulative amount X.” The helper below matches the real test suite: 
function encodeCompactU64(value: bigint): number[] {
  const bytes: number[] = [];
  let remaining = value;
  do {
    let byte = Number(remaining & 0x7fn);
    remaining >>= 7n;
    if (remaining > 0n) byte |= 0x80;
    bytes.push(byte);
  } while (remaining > 0n);
  return bytes;
}

function createCommitmentMessage(params: {
  payerId: number;
  payeeId: number;
  tokenId: number;
  committedAmount: anchor.BN;
  messageDomain: Buffer;
  authorizedSettler?: PublicKey;
}): Buffer {
  const flags = params.authorizedSettler ? 1 : 0;

  const bodyParts = [
    Buffer.from(encodeCompactU64(BigInt(params.payerId))),
    Buffer.from(encodeCompactU64(BigInt(params.payeeId))),
    new anchor.BN(params.tokenId).toArrayLike(Buffer, "le", 2),
    Buffer.from(encodeCompactU64(BigInt(params.committedAmount.toString()))),
  ];

  if (params.authorizedSettler) {
    bodyParts.push(params.authorizedSettler.toBuffer());
  }

  return Buffer.concat([
    Buffer.from([0x01, 0x05]),
    params.messageDomain,
    Buffer.from([flags]),
    ...bodyParts,
  ]);
}
Build the first commitment: 
const channel = await program.account.channelState.fetch(channelPda);

const delta = new anchor.BN(250_000);
const committedAmount = channel.settledCumulative.add(delta);

const message = createCommitmentMessage({
  payerId: channel.payerId,
  payeeId: channel.payeeId,
  tokenId,
  committedAmount,
  messageDomain,
});

​
8. Add the Ed25519 verification instruction

Agon expects the signed message to be verified by Solana’s Ed25519 program inside the same transaction: 
const ed25519Ix = Ed25519Program.createInstructionWithPrivateKey({
  privateKey: alice.secretKey,
  message,
});
The signer above must match the channel’s current authorized_signer. This key signs new cumulative payment amounts for that channel. By default it is the payer wallet that created the channel; if the channel uses a different signing key, that key must sign here instead.
authorized_signer signs the payment update. authorized_settler may submit the signed update on-chain. They are separate roles — see Authorized settler.

​
9. Submit settle_individual

The payee, or an authorized_settler named inside the signed message, submits the settlement transaction: 
await program.methods
  .settleIndividual()
  .accounts({
    channelState: channelPda,
    payerAccount: aliceParticipantPda,
    payeeAccount: bobParticipantPda,
    submitter: bob.publicKey,
  } as any)
  .preInstructions([ed25519Ix])
  .signers([bob])
  .rpc();
The program verifies the Ed25519 instruction, parses the message, checks the message_domain, validates the canonical payer / payee / token / channel, then moves the delta between the old and new cumulative amounts.

​
10. Read the result

After settlement:
  1. channel.settled_cumulative has advanced.
  2. The payer balance has decreased by the delta.
  3. The payee balance has increased by the same amount.
  4. Any locked funds used by the settlement have been consumed first.
If an operator also needs to be paid, model that as a separate channel payment rather than as a fee field inside this message — see Operator payment. That is the full direct settlement flow.

​
Where to go next

Bundle settlement

Settle many payers’ commitments for one payee in a single transaction.

Authorized settler

Let an operator submit on behalf of the payee without changing the signed message.

Cooperative clearing

Compress many payments across many participants into one round.

Message formats

The exact byte layout of agon-cmt-v5 and agon-round-v4.