participant_id for the life of the deployment. Participants deposit allowlisted tokens into protocol balances. When one participant pays another, they create one permanent one-way payment channel for that token. The payer may optionally lock funds to that channel if the relationship needs guaranteed payment capacity.
On-chain objects
V4 exposes four primary account types:| Account | What it stores | Why it exists |
|---|---|---|
GlobalConfig | Authority, fee settings, chain ID, derived message_domain, timelock policy | Defines the deployment and the signing domain |
TokenRegistry | Allowlisted settlement tokens | Makes token support explicit rather than implicit |
ParticipantAccount | Stable participant_id, token balances, withdrawal state, inbound-channel policy | Gives every wallet one durable protocol identity |
ChannelState | One directed channel’s token, payer, payee, settled cumulative, locked funds, signer state | Tracks the durable relationship between one payer and one payee |
Signed messages
V4 uses exactly two signed message formats:agon-cmt-v5— the unilateral cumulative commitment for one channelagon-round-v4— the cooperative clearing-round message for several participants
message_domain, so a signature for one environment does not verify on another. Full byte-level layouts are on the Message formats reference.
Settlement paths
Those two messages feed three settlement instructions:| Mode | Instruction | When to use |
|---|---|---|
| Direct | settle_individual | One payer, one payee — the simplest path |
| Bundle | settle_commitment_bundle | One payee aggregating many payers’ commitments in one token |
| Cooperative clearing | settle_clearing_round | Several participants co-signing one shared round so payments net before balance changes are applied |
End-to-end flow
In the common case, an integration goes through these steps:- Register the payer and payee as participants.
- Deposit an allowlisted token.
- Create a one-way payment channel.
- Optionally lock funds to that channel for guaranteed capacity.
- Sign cumulative commitments off-chain as usage grows.
- Settle the newest valid state later.
What stays off-chain
Agon keeps signed payment updates off-chain until settlement. Most integrations store:- the latest signed
agon-cmt-v5per channel - usage or metering state
- bundle assembly logic
- cooperative round construction logic
Why V4 uses permanent identities and permanent channels
Agon intentionally uses stable identities and permanent channels. The tradeoff is more long-lived on-chain state, but the protocol becomes much easier to work with:participant_idvalues do not recycle.- Off-chain services can index users without worrying about identity reuse.
- Channels do not close and reopen, so there is no reopened-channel replay surface.
- Replay protection is simpler.
- Payment channels stay stable for clients and operators.
Choosing a settlement mode
- Use direct settlement when one payer and one payee need the smallest possible surface and each lane can settle on its own.
- Use bundle settlement when one payee collects signed commitments from many payers in the same token and wants one transaction instead of many.
- Use cooperative clearing when several parties are willing to co-sign one shared round so payments inside the group can cancel out before balances are updated.
Current deployment
| Field | Value |
|---|---|
| Program ID | Ba2puU8D2CLD1dYfRQ4YBXxirdyz3zVLLChvMf9AqJ1Y |
| Cluster | devnet |
| Message domain | b2ba0d07c5a4fcd09b933f732c3f389d |
| Default settlement token | aUSDC (token_id = 2, mint AMXvvKksfCprEKY9uxzNx9MKrDq9kwDWG6Fr9sXkEpAr) |
Where to go next
Your first payment
Build the smallest useful Agon integration with real Anchor calls.
Payment channels
How one-way, permanent channels are modeled and maintained.
Commitments
How cumulative signed messages work and why they are cheap to update.
Instructions
The full on-chain instruction surface.