Skip to content

About

Add wallet-token authentication to your API without disturbing existing API-key customers. Either-or middleware: API-key requests pass through unchanged; wallet-signed requests are verified via InsumerAPI's /v1/attest. Free, MIT, BYO InsumerAPI key.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

@skyemeta/access

npm license release

Add wallet-token authentication to your API without disturbing existing API-key customers.

npm install @skyemeta/access

What it does

You run an API. Today your customers authenticate with an API key. But AI agents already have wallets, and they'd rather authenticate the same way they do everything else: by signing with their wallet.

@skyemeta/access is an either-or middleware:

  • X-API-Key header present → your existing handler runs, untouched. Zero overhead.
  • Authorization: Wallet ... header present → SDK verifies the SIWE signature, then asks InsumerAPI's /v1/attest whether the wallet still holds a valid token from the configured collection. Yes → request passes. No → 401.
  • Neither → 401.

Your humans keep their keys. Your agents use the wallet they were going to carry anyway. Both work on the same routes.

Quick start

import express from 'express';
import { Access } from '@skyemeta/access';

const access = new Access({
  insumerApiKey: process.env.INSUMER_API_KEY!,
  siweDomain: 'api.yourservice.com',
  collections: {
    default: { address: process.env.ACCESS_COLLECTION!, chain: 'base' },
  },
});

const app = express();

app.post(
  '/api/v1/whatever',
  access.requireValidPassOrApiKey(yourApiKeyMiddleware),
  handler,
);

The Authorization: Wallet header carries a standard EIP-4361 (Sign-In with Ethereum) message, read strictly: an EIP-55 checksummed address, Version: 1, fields in the EIP-4361 order, a message of at most 4 KB. Signatures are accepted for five minutes after Issued At, and sooner if the signer set Expiration Time or Not Before.

siweDomain is required and must match what your wallet clients put in their SIWE message domain field. Set it explicitly to the host your API serves SIWE messages for; don't rely on request-host inference behind reverse proxies.

Adopters also bring their own NFT/SBT collection; any ERC-721 works. We used RNWY: the trust intelligence layer for autonomous AI agents. RNWY's audited ERC-5192 factory on Base provides the soulbound issuance substrate for the InsumerAccess collection that backs InsumerAPI's own customers. Other options: Thirdweb, Crossmint, or your own contract. See Get an InsumerAPI key below for the key acquisition step.

Get an InsumerAPI key

The SDK calls /v1/attest on your behalf, so you need an InsumerAPI key in INSUMER_API_KEY.

Wallet-native (recommended for agent infrastructure):

Send USDC to the InsumerAPI platform wallet on a supported chain, sign a short text with the wallet that paid, then POST the transaction hash and that signature. The sender wallet becomes the account's identity: no email, no signup form.

This SDK needs a string key in INSUMER_API_KEY to call /v1/attest from your server, so pass "keyDelivery": "apiKey" to receive one in the response. The endpoint's default is "wallet", which delivers only the on-chain access pass with no string key; that path is for agents calling /v1/attest directly from their own runtime, not for the SDK use case.

curl -X POST https://api.insumermodel.com/v1/keys/buy \
  -H "Content-Type: application/json" \
  -d '{"txHash":"0x…","chainId":8453,"amount":5,"appName":"my-agent","senderSignature":"0x…","keyDelivery":"apiKey"}'

Response (illustrative; key shown only once, store it):

{
  "ok": true,
  "data": {
    "success": true,
    "key": "insr_live_...",
    "authMethod": "apiKey",
    "registeredWallet": "0x...",
    "totalCredits": 125
  }
}

On EVM payments the response also carries a passMint block indicating that a non-transferable Insumer Access pass was minted to the sender wallet. The wallet can then use signed-message auth (Authorization: Wallet) on /v1/attest and /v1/credits/buy directly, handy for top-ups from an agent runtime that prefers signing over carrying the key.

The envelope also includes name, tier, dailyLimit, creditsAdded, usdcPaid, effectiveRate, chainName, authHint, and a top-level meta block; see the OpenAPI spec for the full schema.

Purchases are USDC only, on Ethereum, Base, Polygon, Arbitrum, Optimism, BNB Chain, Avalanche or Solana. USDT, Bitcoin, Tron and any other token are refused, and crypto sent on an unsupported chain cannot be recovered. senderSignature is the paying wallet's signature over five lines joined by a newline, with no trailing newline: api.insumermodel.com, Confirm the wallet that sent this payment., Purpose: key purchase, Chain: eip155:<chainId> (or Chain: solana), and Transaction: <txHash>. A request without it returns 400 with the exact text to sign. See /v1/keys/buy in the OpenAPI spec for the platform wallet addresses per chain and the full request schema, and insumermodel.com/pricing for prices. Minimum purchase is $5. Volume discount tiers: $5–$99 buys 25 credits/$1, $100–$499 buys 33 credits/$1, $500+ buys 50 credits/$1.

Human signup (free tier): no signup, no dashboard, no password:

If you're a human developer and want to try before paying, enter your email at insumermodel.com and the form issues a free key (10 attestation credits, 100 requests/day, no card) inline in about 10 seconds. No account is created; the key is the credential.

Already have a key? Manage usage, top up, or upgrade at insumermodel.com/developers/account/.

What's in scope (v0.2.x)

The SDK's requireValidPassOrApiKey and requireValidPass middleware check NFT ownership on EVM chains (nft_ownership condition against any of the 31 EVM chains InsumerAPI supports: Ethereum, Base, Optimism, Arbitrum, Polygon, etc.). Non-EVM chains (Solana, XRPL, Bitcoin, Tron, Stellar, Sui) and richer condition types (token_balance, eas_attestation, farcaster_id, compound stacks) are reachable via direct calls to InsumerAPI's /v1/attest; the SDK's middleware stays focused on the common case.

Post-quantum companion

InsumerAPI returns an ML-DSA-65 companion (pqJwt) beside the ES256 JWT on every attestation. The SDK checks it on every upstream call and reports it as req.skyemetaAccess.pq (verified, refuted, absent, or unverifiable, with a reason); it is undefined when the request was served from the cache or in local mode. A refuted companion always rejects the pass. An absent or unverifiable companion rejects only once your own pqRequiredFrom date (a config option, judged by this process's clock) has passed; leave it unset to report only. Install the optional peer @noble/post-quantum to verify companions; without it a present companion is reported unverifiable. Other config: jwksUrl and attestBaseUrl override the JWKS and API endpoints for testing. The companion is bound to the ES256 JWT by the full claim set: every claim in the two tokens must match, compared as parsed JSON, so a companion reported verified vouches for everything the SDK reads from the JWT. Only InsumerAPI's attestation signing keys are accepted: the ES256 JWT must be signed by insumer-attest-v1 or insumer-attest-v2, and its companion by insumer-attest-pq1. A malformed pqRequiredFrom stops the middleware at startup. The optional peer loads under bundlers (webpack/Next.js, Turbopack, Vite) as well as plain Node.

Pricing

The SDK is free and MIT-licensed. Each wallet-signed request hits InsumerAPI's /v1/attest once per cacheTtlMs window per (wallet, collection); cached results inside that window skip the upstream call. With the default cacheTtlMs: 2000, a wallet sending five requests in a second triggers one attest call. Adopters running high-throughput or revocation-sensitive flows can shrink the cache or set cacheTtlMs: 0 to disable it. API-key requests never touch InsumerAPI.

When /v1/attest is unreachable, the SDK falls back to its most recent cached result if available and no more than 60 seconds past expiry (MAX_STALE_FALLBACK_MS). Beyond that window it fails closed with a 503. Adopters who need stricter revocation propagation can set cacheTtlMs: 0 to opt out of cache + grace entirely.

Distributed by

Skye Meta Corp.: wrapper layer over InsumerAPI (the wallet-auth primitive: condition-based access, ECDSA-signed booleans with an ML-DSA-65 post-quantum companion, JWKS-verifiable, 37 chains).

License

MIT

About

Add wallet-token authentication to your API without disturbing existing API-key customers. Either-or middleware: API-key requests pass through unchanged; wallet-signed requests are verified via InsumerAPI's /v1/attest. Free, MIT, BYO InsumerAPI key.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages