Version 2.1.4. Native Polygon v1.4 execution with pinned runtime, signer and current profile checks is released (since 2.1.0). fetchPaid buys Polygon v1.4 receipts through explicit v14 authorization, a durable pre-broadcast journal, a fresh independent POL/USD rate you supply (nativeUsdPrice) and a separate gas cap. Stable-token v1.4 execution and legacy call() remain unavailable.

For nativeUsdPrice, any source independent of the quote works: Chainlink POL/USD on Polygon (0xAB594600376Ec9fD91F8e885dADF0CE036862dE0, 8 decimals), Coinbase POL-USD, or CoinGecko id polygon-ecosystem-token (not the retired matic-network, which stopped updating in February 2026).

Link the agent to its owner's dashboard

At https://dash.aifinpay.io → My Agents → Add agent by address the owner gets a challenge. Sign it and hand back the signature:

const signature = await agent.signDashboardClaim(challenge);

signDashboardClaim signs only AiFinPay-claim:polygon:<this address>:<nonce> and refuses any other text. The owner then sees the agent's balance, payments and receipts.

The accepted v1.4 contract model allows administrators to change profile fees and treasury. Preflight verifies current values; it does not make them immutable. See receipt configuration and recovery.

Non-custodial payment client for autonomous AI agents on AiFinPay. AIFP-1 is gross-inclusive: payer total equals the quote, merchant receives 99%, AiFinPay receives 1%, creator/referral receives 0%. AIFP-2/x402 currently charges 0% at the protocol layer. Legacy /api/b2b split-invoice methods are retired. The v1.3 executor checks the independently supplied deployment/runtime pin, chain, fee profile, merchant target and asset. Deployment activation and funded E2E approval remain separate operator responsibilities; a matching runtime hash alone is not production-readiness evidence.

The Ed25519 keypair is generated locally with tweetnacl and never leaves your process. The SDK only sends a one-time SHA-256 + Ed25519 signature in the x-signature header to authenticate against AiFinPay-protected endpoints.

Install

Install the published stable package:

npm install @aifinpay/agent

Or build this source checkout:

# From the SDK repository root
cd node
npm ci --no-audit --no-fund
npm run build
npm pack

Install the resulting tarball in your application:

npm install /absolute/path/to/sdk/node/aifinpay-agent-2.1.0.tgz

Quick start

Load the wallet you already configured before sharing a deposit address:

import { AiFinPayAgent } from "@aifinpay/agent";

const agent = await AiFinPayAgent.fromEnvironment();
console.log({ evm: agent.evmAddress, solana: agent.solanaAddress });

fromEnvironment() is a load-only Node API. It selects one identity in this order, matching MCP:

SEED_HASH: a 32-byte seed encoded as 64 hex characters, optionally 0x prefixed.
./aifinpay/agents.json relative to the process working directory. Set AIFINPAY_AGENTS_FILE for another path and AIFINPAY_AGENT_ID when selecting from multiple records ({"agents":[{"id":"crawler","seed_hash":"…"}]}).
AIFINPAY_AGENT_SECRET: an existing base58 Solana secret.
~/.aifinpay/agent.json, or AIFINPAY_HOME/agent.json: the existing MCP keystore. Encrypted keystores require AIFINPAY_WALLET_PASSPHRASE.

The loader never creates or overwrites a wallet, prints its keys, or calls the network. Missing configuration, an invalid seed, an ambiguous project file or a decryption failure throws instead of selecting a new wallet. Load any .env through your runtime before calling it; this API reads process.env and does not read .env files. SEED_HEX is not an alias for SEED_HASH. Keep private inputs and wallet files out of chats, logs and version control.

The same configured inputs restore the same addresses after a process restart. An explicit evmPrivateKey option overrides the derived EVM identity; retain that separate key as well to recover the imported wallet. Loading a wallet does not enable the RC's gated settlement routes.

AiFinPayAgent.new() and Agent.new() intentionally create a fresh ephemeral wallet each time. They do not load existing environment variables or keystores and do not persist their generated keys. Use them only when you deliberately need a new identity and will store its recovery material privately before funding it. Never rerun new() to recover an existing funded address.

Loading an existing keypair

import { Agent } from "@aifinpay/agent";

// from solana-keygen JSON file (Node only)
const agent = await Agent.fromKeypairFile("./agent-wallet.json");

// from base58 secret string (works in browser too)
const agent2 = Agent.fromSecretB58("3RvZm7Gw...");

How x402 auth works under the hood

For every gated request the SDK:

GET /nonce → receives a one-time UUID with 60s TTL.
computes SHA-256("AiFinPay-x402:{nonce}:{pubkey}").
signs with Ed25519, base58-encodes the signature.
retries the original request with headers:
- x-agent-pubkey: <base58 pubkey>
- x-nonce: <uuid>
- x-signature: <base58 sig>

The server verifies the signature, checks the agent has a live Seat PDA on-chain, and serves the resource.

Privacy

The server never sees your private key. Period.
Nonces are consumed on use; replay-resistant.
All transactions are public and on-chain — Solana + Polygon mainnet.

License

MIT.

Payment receipt authorization

AIFP-1 receipts use the paying wallet signature. See authorize and recover payment receipts for retries and recovery without a second transfer.

Payment history

import { getAgentHistory } from "@aifinpay/agent";
const history = await getAgentHistory({ address: "0x…", source: "transactions" });
// Or { passport: 'AIFP-000000042', network: 'polygon', source: 'receipts' }

transactions covers indexed AiFinPay Polygon settlements, not arbitrary wallet transfers. receipts covers retained prepaid batches, including test payments. Follow next_offset with limit/offset. A passport requires a backend with the verified-wallet resolver deployed; passing both address and passport checks their match. Never pass a holder private key or API secret as an identifier. Public history does not return bearer receipt tokens.