@usenami/plugin-funding

ElizaOS plugin: multi-venue perpetual funding-rate data and cross-exchange funding arbitrage across 20+ exchanges — a free screener plus paid x402 signals that auto-pay per call.

This is the public source mirror of @usenami/plugin-funding, the ElizaOS plugin for Usenami's funding-rate data. It's a thin client over the public Usenami funding API — the same HTTP + x402 contract as the @usenami/funding-mcp MCP server, so the same endpoints and wallet work with either.

Why

Perpetual funding rates drift apart across exchanges constantly. Knowing where funding is richest — and which long-venue / short-venue pairs give the best delta-neutral spread right now — is a live, perishable signal. This plugin gives an ElizaOS agent that signal directly: a free screener to scan the whole market, and two paid endpoints for the ranked arbitrage view, settled per-call in USDC on Base via x402 so there's no API key, account, or subscription to manage.

Install

npm install @usenami/plugin-funding

Quickstart

Add the plugin to your character. The free screener needs no config. To let the paid actions auto-pay, set X402_PRIVATE_KEY to a Base wallet holding a little USDC:

import fundingPlugin from "@usenami/plugin-funding";

export const character = {
  // ...existing config
  plugins: [fundingPlugin],
  settings: {
    secrets: {
      // optional — only needed for the paid actions:
      X402_PRIVATE_KEY: "0x<your-base-wallet-private-key>",
    },
  },
};

For local dev you can also put the same vars in .env.

Actions the agent gets

| Name | Cost | Purpose | |---|---|---| | FUNDING_SCREENER | free | Current cross-venue funding rates across 20+ exchanges. Optional symbol filter. No wallet. | | FUNDING_ARB | ~$0.003 (x402) | Ranked long-venue / short-venue funding-arbitrage pairs (delta-neutral). Optional symbol filter. | | FUNDING_SPREAD | ~$0.001 (x402) | Funding-rate spread for one symbol across all venues (min/max venue, basis). |

If X402_PRIVATE_KEY is set, the paid actions auto-pay the x402 challenge and return the data. If it's not set, they return the x402 payment requirements instead, so any x402-capable agent can pay the call itself and retry. The free screener never touches a wallet.

Coverage

20+ venues including Binance, Bybit, OKX, Hyperliquid, Aster, Lighter, and Hyperliquid HIP-3 sub-DEXes (where on-chain RWA / niche perp funding lives). The set the API ranks over is broader than any single exchange's view.

Env contract

Same as @usenami/funding-mcp:

| Var | Default | Purpose | |---|---|---| | USENAMI_API_BASE | https://api.usenami.io | API base URL. | | X402_PRIVATE_KEY | (unset) | Base wallet (0x + 64 hex) that auto-pays the paid endpoints over x402. Optional. | | FUNDING_FETCH_TIMEOUT_MS | 30000 | Per-request timeout. |

Payment model

• Free screener. FUNDING_SCREENER is a public preview — no wallet, no payment.
• Per-call x402. The paid endpoints answer an HTTP 402 with x402 payment requirements; with a wallet configured the plugin settles it in USDC on Base and retries automatically. No account, no subscription — you pay only for the calls you make.
• No key custody. The plugin holds nothing but the optional Base wallet you give it; there's no Usenami API key to leak.

Links

• Landing: usenami.io
• npm: @usenami/plugin-funding
• MCP server (Claude Desktop / Cursor): @usenami/funding-mcp
• Sibling plugin (keyless perp signing): @usenami/plugin-signer

License

MIT — see LICENSE.