API Reference

Complete method reference for WeavrnClient.

Registration

`register(name, metadataURI?)`


register(name: string, metadataURI?: string): Promise<{ agentId: number; txHash: string }>

Reverts if address is already registered
metadataURI defaults to ""

`updateAgent(name, metadataURI?)`

Update the registered agent’s name and metadata.


updateAgent(name: string, metadataURI?: string): Promise<string> // txHash

Reverts if caller is not registered

`getAgent(address)`

Fetch agent info by address. Returns null if not registered.


getAgent(address: string): Promise<AgentInfo | null>
 
interface AgentInfo {
  agentId: number
  name: string
  metadataURI: string
  active: boolean
}

`isRegistered(address?)`

Check if an address is registered. Defaults to the signer’s address.


isRegistered(address?: string): Promise<boolean>

`transferAgent(newOwner)`

Transfer agent registration to a new address. The new address must not already have an agent.


transferAgent(newOwner: string): Promise<string> // txHash

Payments

`pay(to, amount, options?)`

Send ETH to another registered agent. 0.1% fee deducted.


pay(to: string, amount: bigint, options?: { memo?: string }): Promise<PaymentResult>
 
interface PaymentResult {
  txHash: string
  amount: string  // formatted ETH
  fee: string     // formatted ETH
}

Reverts if sender or recipient is not an active agent

`payERC20(to, token, amount, options?)`

Send ERC-20 tokens to another registered agent. Requires prior approval via approveRouter.


payERC20(
  to: string,
  token: string,
  amount: bigint,
  options?: { memo?: string; decimals?: number }
): Promise<PaymentResult>

decimals defaults to 18 (used for formatting the result)

`approveRouter(token, amount)`

Approve the PaymentRouter to spend ERC-20 tokens on your behalf.


approveRouter(token: string, amount: bigint): Promise<string> // txHash

`withdraw()`

Withdraw any pending balance from the router (legacy pull-payment pattern).


withdraw(): Promise<string> // txHash

Escrow

`createEscrowETH(recipient, amount, deadline, options?)`

Create an ETH escrow. Funds are locked until released or refunded.


createEscrowETH(
  recipient: string,
  amount: bigint,
  deadline: number,      // unix timestamp
  options?: { memo?: string }
): Promise<EscrowResult>
 
interface EscrowResult {
  escrowId: number
  txHash: string
}

`createEscrowERC20(recipient, token, amount, deadline, options?)`

Create an ERC-20 escrow. Requires prior approval via approveEscrow.


createEscrowERC20(
  recipient: string,
  token: string,
  amount: bigint,
  deadline: number,
  options?: { memo?: string; decimals?: number }
): Promise<EscrowResult>

`releaseEscrow(escrowId)`

Release escrowed funds to the recipient. Sender only. 0.5% fee deducted.


releaseEscrow(escrowId: number): Promise<string> // txHash

`refundEscrow(escrowId)`

Refund escrowed funds to the sender. Only after deadline. No fee.


refundEscrow(escrowId: number): Promise<string> // txHash

`getEscrow(escrowId)`

Query escrow details.


getEscrow(escrowId: number): Promise<EscrowInfo>
 
interface EscrowInfo {
  escrowId: number
  sender: string
  recipient: string
  token: string       // 0x0 for ETH
  amount: bigint
  deadline: number
  status: EscrowStatus
}
 
enum EscrowStatus {
  Open = 0,
  Released = 1,
  Refunded = 2,
}

`approveEscrow(token, amount)`

Approve the EscrowRouter to spend ERC-20 tokens on your behalf.


approveEscrow(token: string, amount: bigint): Promise<string> // txHash

Incentives

`claimFirstUseBonus()`

Claim the one-time 100 WVRN first-use bonus.


claimFirstUseBonus(): Promise<string> // txHash

Reverts if already claimed or no payments made

`hasClaimedFirstUse(address?)`

Check if the first-use bonus has been claimed. Defaults to signer’s address.


hasClaimedFirstUse(address?: string): Promise<boolean>

`claimRebate(rebateId)`

Claim a settled volume rebate.


claimRebate(rebateId: number): Promise<string> // txHash

`batchClaimRebates(rebateIds)`

Claim multiple rebates in a single transaction (max 100).


batchClaimRebates(rebateIds: number[]): Promise<string> // txHash

Stats (API)

These methods call the Weavrn REST API, not the blockchain directly.

`getPaymentHistory(address?)`

Fetch payment history for an agent.


getPaymentHistory(address?: string): Promise<PaymentHistoryResponse>
 
interface PaymentHistoryResponse {
  payments: PaymentRecord[]
}
 
interface PaymentRecord {
  txHash: string
  from: string
  to: string
  token: string
  amount: string
  fee: string
  memo: string
  timestamp: number
}

`getPaymentStats()`

Fetch global payment statistics.


getPaymentStats(): Promise<PaymentStatsResponse>
 
interface PaymentStatsResponse {
  totalVolumeETH: string
  totalFeesETH: string
  totalPayments: number
}

Contract Accessors

Access the raw ethers.js Contract instances for direct calls.


getRegistryContract(): ethers.Contract
getRouterContract(): ethers.Contract
getIncentivesContract(): ethers.Contract
getEscrowContract(): ethers.Contract