Skip to Content
Devnet Preview: data may reset, no production guarantees.
SDK ReferenceSolanaPayer

SolanaPayer — Payment Helper

SolanaPayer handles Solana payment transactions for all paid Provenonce operations: SIGIL purchase, heartbeat, and passport reissue. It auto-fetches fees, builds transactions, signs, sends, and polls for confirmation — turning 15 lines of boilerplate into a single call.

Import: @provenonce/sdk/solana (separate entrypoint — does NOT bundle with the core SDK)

Peer dependencies: @solana/web3.js, bs58

Quick Start

import { SolanaPayer, createPayer, createHeartbeatPaymentFn } from '@provenonce/sdk/solana';
import { BeatAgent, register } from '@provenonce/sdk';
 
// Create payer from base58 secret key
const payer = createPayer(process.env.WALLET_SECRET!, 'https://provenonce.io');
 
// SIGIL purchase — 2 lines instead of 15
const { signature } = await payer.paySigil('narrow_task');
await agent.purchaseSigil({ identity_class: 'narrow_task', principal: 'acme', tier: 'ind', payment_tx: signature });
 
// Heartbeat — 2 lines
const { signature: hbSig } = await payer.payHeartbeat();
await agent.heartbeat(hbSig);
 
// Autonomous heartbeat loop — 1 line
agent.startHeartbeat(createHeartbeatPaymentFn(payer));

Constructor

new SolanaPayer(config: SolanPayerConfig, registryUrl: string)
ParameterTypeRequiredDescription
config.keypairKeypairYesSolana keypair that signs transactions
config.rpcUrlstringNoSolana RPC URL (default: https://api.devnet.solana.com)
config.commitmentstringNo'confirmed' or 'finalized' (default: 'confirmed')
registryUrlstringYesRegistry URL (e.g., 'https://provenonce.io')

Methods

getFees(): Promise<FeeSchedule>

Fetches the current fee schedule from GET /api/v1/fees/summary. Cached for 5 minutes.

const fees = await payer.getFees();
console.log(fees.payment_address);        // ops wallet address
console.log(fees.schedule.sigil_tiers);   // SIGIL pricing by identity class
console.log(fees.schedule.heartbeat_tiers); // heartbeat pricing by volume

sendPayment(lamports: number): Promise<PaymentResult>

Low-level: sends lamports to the operations wallet. Returns { signature, lamports }.

If lamports <= 0, returns { signature: 'sandbox-free', lamports: 0 } without making a transaction.

paySigil(identityClass: string): Promise<PaymentResult>

Pays the SIGIL fee for the given identity class. Automatically looks up the correct fee.

const { signature } = await payer.paySigil('narrow_task');   // 0.05 SOL
const { signature } = await payer.paySigil('autonomous');     // 0.15 SOL
const { signature } = await payer.paySigil('orchestrator');   // 0.35 SOL

Sandbox tier returns { signature: 'sandbox-free', lamports: 0 } — no Solana transaction.

payHeartbeat(heartbeatCount?: number): Promise<PaymentResult>

Pays the heartbeat fee. Optionally pass the current heartbeat count for tiered pricing:

CountFee
1–1000.0005 SOL
101–1,0000.0003 SOL
1,001+0.0002 SOL
const { signature } = await payer.payHeartbeat();
await agent.heartbeat(signature);

payPassportReissue(): Promise<PaymentResult>

Pays the passport reissue fee.

const { signature } = await payer.payPassportReissue();

getBalance(): Promise<number>

Returns the payer’s SOL balance in lamports.

const balance = await payer.getBalance();
console.log(`${balance / 1e9} SOL`);

publicKey: string (getter)

Returns the payer’s public key as base58.

Factory Functions

createPayer(secretBase58, registryUrl, rpcUrl?): SolanaPayer

Creates a SolanaPayer from a base58-encoded secret key (the 64-byte Solana keypair format).

import { createPayer } from '@provenonce/sdk/solana';
 
const payer = createPayer(
  process.env.WALLET_SECRET!,
  'https://provenonce.io',
  'https://api.devnet.solana.com',  // optional
);

createHeartbeatPaymentFn(payer): () => Promise<string>

Returns a function compatible with agent.startHeartbeat(). Tracks heartbeat count for tiered pricing.

import { createHeartbeatPaymentFn } from '@provenonce/sdk/solana';
 
// Autonomous heartbeats with automatic payment
agent.startHeartbeat(createHeartbeatPaymentFn(payer));

Types

interface PaymentResult {
  signature: string;  // Solana tx signature, or 'sandbox-free'
  lamports: number;   // Amount paid (0 for sandbox)
}
 
interface FeeSchedule {
  payment_address: string;
  payment_chain: string;
  schedule: {
    sigil_tiers: Array<{ identity_class: string; label: string; sol: number; lamports: number }>;
    heartbeat_tiers: Array<{ from: number; to: number | null; sol: number; lamports: number }>;
    proof_reissuance_sol: number;
  };
}
 
interface SolanPayerConfig {
  keypair: Keypair;
  rpcUrl?: string;
  commitment?: 'confirmed' | 'finalized';
}

MCP Auto-Payment

When using the MCP Skill, set PROVENONCE_WALLET_SECRET to enable auto-payment for all paid operations:

{
  "mcpServers": {
    "provenonce": {
      "command": "npx",
      "args": ["-y", "@provenonce/mcp@latest"],
      "env": {
        "PROVENONCE_WALLET_SECRET": "your-base58-secret-key"
      }
    }
  }
}

With auto-payment configured, provenonce_heartbeat and provenonce_purchase_sigil no longer require payment_tx — the MCP server handles it automatically.

When NOT to Use SolanaPayer

  • Browser dApps: Use wallet adapters (Phantom/Solflare) instead — the user signs in their browser wallet
  • Custodial agents: When a separate payment system handles SOL transfers
  • Custom fee routing: When you need to pay to a different recipient
Last updated on
register()updateMetadata()