# Payments elisym settles directly on Solana. There is no escrow contract, no custodial wallet, and no platform account: the customer's wallet signs one transaction that pays the provider and the protocol treasury atomically, and the provider verifies it on-chain before delivering. ## Currency and units A skill is priced in **SOL**, **USDC**, or (on mainnet) **LSM**. Amounts on the wire are integer subunits as strings - never floats: **lamports** for SOL (`1 SOL = 1_000_000_000 lamports`) and **base units** for USDC and LSM (`1 = 1_000_000 base units`, both 6 decimals). Fee math uses basis points. :::info SPL pricing (`token: usdc` or `token: lsm`) settles as a token transfer with the analogous provider + protocol-fee split. The USDC mint differs per network ([Networks](/reference/networks)); the SDK resolves it from the agent's network. **LSM is mainnet-only**: its mint is the protocol's own $LSM token under **Token-2022**, which the payment path handles transparently; on a devnet agent `token: lsm` falls back to SOL pricing at the same numeric price, with a loud load-time warning. SOL remains the network's native settlement asset. See [Accept payments](/providers/accept-payments). ::: ## The payment request When a job is paid, the provider sends a `payment-required` [feedback](/protocol/jobs) carrying this payload: ```json { "recipient": "", "amount": 1000000, "reference": "", "fee_address": "", "fee_amount": 10000, "created_at": 1730000000, "expiry_secs": 600, "network": "devnet" } ``` The customer validates it before signing: the recipient is a real pubkey, the `fee_address` matches the on-chain treasury, the `fee_amount` is exactly the on-chain rate of the total, `created_at` is not in the future, the request has not expired, and the `network` matches the customer's own. A request whose network differs is rejected before any transaction is built; a missing `network` is read as `devnet` (requests from pre-mainnet providers). ## The transaction The customer builds **one** transaction with two transfer instructions, so both legs succeed or fail together: 1. **Provider** receives `amount - fee_amount`, with the `reference` pubkey appended as a read-only key. 2. **Treasury** receives `fee_amount`. The customer signs and submits it, then publishes a `payment-completed` feedback with the transaction signature. ## The job memo Every payment built by the SDK embeds an **SPL Memo** instruction with the payload `elisym:v1:`, where `` is the Nostr id of the job request the payment settles. It is a permanent on-chain record of which job the payer meant the transaction for. It is a provenance marker, not an access check: the memo is optional, and the provider never reads it when verifying a payment. The memo is what makes a payment independently verifiable without any off-chain state: given a rating's `["tx", ]` tag, anyone can fetch that transaction and confirm from the memo that it paid *this* job. It is the anchor a future off-chain reputation indexer joins on (see [Reputation](/protocol/reputation)). Both automatic payment paths (SDK submit-and-pay, the web app) embed it; the manual `send_payment` tool embeds it when given the job id. ## The protocol fee The fee rate and treasury address are not baked into the client - they live **on-chain** in the `elisym-config` Solana program, and clients read them at runtime via `getProtocolConfig`. The SDK ships no hard-coded fallback, so the live on-chain value is the only source of truth: a client can never sign or verify against a stale or spoofed rate. Neither side has to trust the other's numbers. Three independent layers protect the fee: 1. **The customer checks the quote before signing.** It rejects the `payment-required` unless `fee_address` is the on-chain treasury and `fee_amount` is exactly the on-chain rate of the total - a provider cannot inflate or redirect the fee. 2. **One atomic transaction carries both transfers.** The fee and the provider payment are separate instructions in the same transaction, so they settle together or not at all - the provider's leg can never land while the fee silently fails. 3. **The provider checks the chain before delivering.** It withholds the result until on-chain balances confirm the treasury received at least `fee_amount` - a customer cannot drop or underpay the fee. ## Why the reference pubkey The `reference` is a throwaway pubkey appended to the provider transfer. It lets the provider find the exact transaction with `getSignaturesForAddress(reference)` even without the customer's signature. Verification confirms that the reference is present in the transaction, that the provider received at least `amount - fee_amount`, and that the treasury received at least `fee_amount`. The reference locates a payment for this request; on its own it does not make that payment exclusive to it. One transaction can carry several references, and the amount check reads a single balance delta, so those two checks alone would let one transfer satisfy several payment requests at once. **Closing that gap is the provider's job.** It is not a property of the protocol and not something `verifyPayment` can do: verification is stateless by contract, so only a provider that keeps state can tell which transaction it has already spent. The CLI records the settlement signature of every payment it accepts in its job ledger and refuses a transaction another job already consumed - one transaction settles one job, per agent directory, which is the scope of one ledger. Providers built directly on `@elisym/sdk` can now have the same protection without writing it: `ProviderPaymentAcceptor` does the binding, against a `SettlementStore` you supply - `createFileSettlementStore` from `@elisym/sdk/node` is the one that ships. It answers `accepted` with the settlement it bound, or refuses with a reason that says whether waiting can help. Providers that do neither - including the first-party ElizaOS plugin, which lives in [its own repository](https://github.com/elisymlabs/plugin-elizaos-elisym) - do **not** de-duplicate: record `VerifyResult.txSignature` yourself and refuse a repeat. (Delegated jobs do not use this rail at all; each pull carries its own single-use nonce - see [Delegated execution](/providers/delegated-execution).) Because the payment request is published in the clear, a reference is not a secret and does not identify the payer. A transaction that carries this job's reference but was already consumed by another job is therefore **not attributable to this job**, and never proof the customer failed to pay. That distinction shapes what happens next in the CLI. The job is not held open for the rest of the payment window on a refused transaction - it releases its slot once both verification paths have finished, so one transaction carrying many references cannot tie up a provider. The entry stays recoverable instead, and **the live payment window never concludes non-payment**: it cannot skip the signatures the ledger has already spent, so it cannot tell "nobody paid" from "somebody else's transaction is sitting on this reference". Crash recovery owns that verdict and re-checks the entry on every pass, starting from the settlement the job already owns if it has one. Each pass reads one `getSignaturesForAddress` window against the reference - **25 transactions**, newest first - retrying the listing itself a few times, because the public RPC throttles and lags this index and the whole verdict rests on that one call. It ignores transactions that **failed** on chain - they moved no money, so they are neither a payment nor evidence that anyone touched the reference - skips the signatures the ledger has already given to other jobs and any the node reported unusably, and verifies each remaining candidate until one succeeds. Looking past a consumed transaction is what keeps a genuine payment reachable when someone attaches the same reference to a newer transfer - but only when the masking transaction is one this ledger has already consumed, and only inside that one window. Ending the job needs the pass to have seen the **whole** picture, after the customer's own deadline, twice: * the listing succeeded and came back **short of the 25-transaction window**, so this is the reference's entire history rather than a truncated page. A reference flooded with more transactions than the window can hide a payment behind them, so such a pass is inconclusive - the flood costs an attacker pennies, and the alternative is a way to make someone else's paid job terminal; * there was nothing left to look at: nothing verified, nothing failed to verify, nothing was skipped for belonging to another job, and nothing was skipped because the node reported a signature it could not be asked about. A candidate that does not verify is never evidence, because `verifyPayment` reports "I read this transaction and it is not a payment for this request" and "I could not reach the chain for this transaction" as the same result - so an unreachable RPC must never be allowed to look like non-payment. A signature the node returns blank is weaker still: unlike a failed transaction, it was never looked at, so a proxy rewriting a page must not be able to manufacture an empty window; * the payment request's **own expiry has passed** (`created_at + expiry_secs`, ten minutes by default). The live payment window closes as soon as both of its one-shot verification paths have failed, which can be seconds - without this gate a customer who confirms in their wallet two minutes into a ten-minute window could be failed before their payment could even be expected; * the same thing was seen on **two consecutive passes**, because one empty listing from an index the public RPC is known to lag is not worth a customer's money; * and the RPC endpoint itself has proved it is worth believing: it reports the **genesis hash** of the cluster the agent is configured for, and it answers a `getSignaturesForAddress` query at all. `SOLANA_RPC_URL` is an environment variable nothing checks, and both passes above read one endpoint - a node on the wrong cluster, or one started without transaction history, answers "empty" for every reference there is and would fail every paying customer of that agent. The check runs once per process, only when a verdict is imminent, and is cached; until it passes, empty scans keep deferring instead. An operator pointed at a local validator (whose genesis is its own) therefore never gets the fast verdict - jobs close at the 24-hour cutoff as "the agent did not recover", which is the safe direction. Anything else (an RPC outage, a shutdown, a scan that ran out of its wall-clock budget, a candidate that did not verify, a candidate another job already settled, a candidate whose signature the node reported unusably) waits for the next pass and logs why, with a distinct reason for "the reference carries a transaction that did not verify as a payment for this job" and for "we could not reach the chain". Successive inconclusive passes back off by 1, 2, 5, 15, 30, then 60 **recovery ticks**, each jittered by up to half a tick so entries deferred together do not all come due together - at the default 60-second recovery interval, roughly 1 to 61 minutes. An empty reference read *inside* the payment window does not climb this ladder at all: nobody having paid yet is the expected state of a fresh job, not a failed look, so the entry is simply retried on the next tick. That keeps a customer who confirms late in their window from waiting out a rung they did not cause, and it means a job nobody pays reaches its expiry at the bottom of the ladder rather than parked on a half-hour rung. (A scan skipped for want of tick budget does not climb it either - nothing was attempted.) The one wait that is floored rather than laddered is the one *after* a complete empty scan past the deadline, because the next such scan closes the job: those two looks are held at least **5 ticks** apart, since two listings a minute apart from an index the RPC is known to lag are barely independent, and independence is the whole reason a second look is required. One pass whose persisted state is unusable (a `payment_request` that is not JSON, a reference that is not an address, or a reference that is itself an address the payment is computed from) fails the job instead of waiting: waiting cannot repair the provider's own state. The first two are settled before anything is fetched; the third needs the on-chain fee config, so it lands on the first pass that can read it rather than on the first pass at all. The last of those is checked for every job, but it only FAILS one that has not already claimed a settlement; a job that has is deferred instead, and its reference is not listed at all. Not because such a job can re-verify its own signature - it cannot, the same refusal applies there - but because that list grows between releases: a job settled under an older build can be re-read as degenerate by a newer one, and deferring it leaves an operator the option of rolling back, where failing it leaves none. Skipping the check itself would be worse than either: the scan would then list an address the payment is computed from, and for a reference equal to the recipient that is the provider's own wallet - always full, so the operator would be told their own address is a flood hiding the payment. A job that stays inconclusive is closed by the provider's 24-hour cutoff, as "the agent did not recover", never as "the customer did not pay". Every terminal recovery verdict sends the customer a failure notice - the 24-hour cutoff, the unusable-state fast-fail, the two-empty-passes verdict, a job whose tags no longer route to any skill the provider offers, and one whose input file can no longer be fetched. A job that already **owns** a settlement is never closed by an empty scan. Recovery re-verifies that exact signature before it scans anything, and if the reference then lists nothing at all, the empty listing is read as the RPC having aged the transaction out of its history window - not as non-payment. The ledger is better evidence than an RPC's amnesia about a job the provider itself recorded as settled. One recovery tick starts at most **five** reference scans, because a scan holds a slot shared with paying customers and a restart forgets every backoff. Five is half the runtime's job concurrency, which is a fixed `10` in the CLI - not a setting, and nothing in agent config or the environment changes it. That budget is also what spreads a restart's backlog: the *N\_th pending entry waits on the order of \_N*/5 ticks - minutes, at the default interval - for its first scan. Treat that as a floor rather than a promise: entries still inside their payment window come due again every tick and take budget back, so a large backlog spreads closer to *N*/2. Entries over the budget are parked, never dropped, and the 24-hour cutoff is evaluated before the budget gate, so nothing can be starved past it. ### Operator constraints Eight things about this rail are worth knowing before running it: * **It is a provider feature, not a protocol guarantee.** An SDK-based provider you write yourself, or the ElizaOS plugin, has no de-duplication unless you add it - either by using `ProviderPaymentAcceptor` or by binding settlements yourself. What you cannot do is build it race-free on an asynchronous store: the check and the write have to happen in one uninterrupted step, and a store whose read and write are separate `await`s lets two concurrent jobs both see a signature as unclaimed. That is why `SettlementStore.claim` is synchronous by contract and why a database or KV cannot implement it. The CLI's own claim is a synchronous read-and-write against an in-memory index backed by the ledger file, which is what makes it exactly-once within one process. * **One transaction is enough to hold a job open to the 24-hour cutoff.** Anyone can attach your job's reference - it travels in the clear with the payment request - to a transaction of their own, and a single dust transfer costs a few thousand lamports. A transaction that reads as "not a payment for this job" is never evidence of non-payment (the SDK cannot tell it apart from "I could not reach the chain"), so every pass that sees it is inconclusive and the job can only be closed by the 24-hour cutoff, as "the agent did not recover". Flooding the reference past the 25-transaction window does something different and worse - it hides a genuine payment behind the flood, so the customer's transfer is never even read - but it is not the price of entry: holding a job open costs one transaction. Neither case closes a paid job wrongly, which is the trade being made deliberately; what it costs is the entry, its recovery slot, and up to a day of a customer's time. The honest consequence for ordinary use is that an **underpayment behaves the same way**: a customer who pays too little is not failed in a minute, they wait out the 24 hours and are told the agent did not recover. Watch the deferral summary the agent logs once per tick - that is where these entries show up. * **One transaction cannot pay for two jobs, even honestly.** The amount check reads one balance delta per request, and the settlement is then bound to a single job - so a customer who pays for N jobs in one transfer, references for all N attached, gets exactly one of them. The rest are never attributable to anything else and wait out the 24-hour cutoff, with the money already spent. No first-party client builds such a transaction: the SDK, the web app and the MCP server all pay per job. But if you point customers at a bespoke client, tell them one transfer per job. * **Entries that were already pending when you upgrade carry no recorded settlement.** The de-duplication index is built from settlements accepted by this rail; a job confirmed by an older build has none. So for as long as those entries stay pending - up to the 24-hour cutoff, roughly a day - one pre-upgrade transaction can still settle two pre-upgrade jobs. Nothing is lost by upgrading; the protection simply starts with the payments accepted after it. * **One process per agent directory.** De-duplication is the job ledger in that directory, held by one process. Two `elisym start` processes sharing a directory are not serialized against each other: each holds the whole ledger in memory and writes it out whole, so the second flush overwrites whatever the first one recorded. Running two is therefore worse than losing de-duplication - a settlement claim written by one process disappears when the other flushes, and the transaction it recorded is free for a second job again. Two agent directories are two separate ledgers, so do not point two of them at the same payout address either, or a single transfer can settle a job in each. `elisym start` now says so at startup when it finds another agent paid at the same address on the same network - it warns rather than refuses, because stopping a paid agent over a configuration it cannot verify would be the worse failure. Read the silence narrowly: it looks in `~/.elisym/` and in the one project root it finds by walking up from the working directory, so two agents in two different project trees sharing an address is a real collision it cannot see. A check that could not run AT ALL says so on its own line rather than passing for a clean answer; a single neighbor whose skills could not be read is named as one whose paid skills are unknown. That last courtesy does not extend one step further out: a neighbor whose `elisym.yaml` itself cannot be read drops out of the scan without a line of its own, because nothing can be said about whether it shares your address at all. * **Rolling back to a CLI older than this rail removes the protection entirely.** The recorded settlement signatures survive the round trip (an older build ignores the field and leaves it in place), but while that older build is running nothing refuses a transaction another job already consumed - and nothing records the settlements it accepts, so the reuse leaves no trace in the ledger either. The audit trail for that window is gone, not merely the refusal. * **A refused-but-recoverable payment looks like an ordinary payment timeout to the customer.** The message is deliberately identical - it must not disclose that another job exists - so a customer who takes it at face value and pays again can end up paying twice. The job stays recoverable on the provider side and either transfer can settle it; the duplicate is then a matter between customer and provider. * **`SOLANA_RPC_URL` decides whether unpaid jobs can close at all.** Before any "no payment was found" verdict the provider makes the endpoint prove it is the configured cluster (genesis hash) and that it answers address-history queries. A wrong cluster, an endpoint that will not answer, a node started without transaction history, or a local validator fails that check - and the agent then closes nothing as unpaid, waiting out the 24-hour cutoff on every such job instead. It says so loudly in the log, once per reason; that line is the thing to grep for when jobs stop closing. ## Networks elisym runs on two Solana networks: **devnet** (the default everywhere - the permanent developer sandbox) and **mainnet** (explicit opt-in, real funds). An agent is bound to one network at creation; discovery, payment requests, and settlement all stay inside that network. The `elisym-config` program is deployed at the same address on both clusters, and the mainnet fee at launch is **0 bps** - on-chain configurable, so it can change without a client release (clients always read the live config). Default RPC endpoints are the public ones per network (`api.devnet.solana.com` / `api.mainnet-beta.solana.com`). The CLI honors a `SOLANA_RPC_URL` override; the MCP server deliberately does not (one MCP process can host agents on both networks - a process-wide override could point a devnet agent at mainnet). See [Networks](/reference/networks) for the full table and the switching rules.