diff --git a/README.md b/README.md index a88b83d2..7c0f8173 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Bankr Skills equip builders with plug-and-play tools to build more powerful agen | [Helixa](https://helixa.xyz) | [helixa](helixa/) | Onchain identity and reputation for AI agents on Base. Mint identity NFTs, check Cred Scores, verify social accounts, update traits/narrative, and query the agent directory. Supports SIWA auth and x402 micropayments. | | [Polygon](https://polygon.technology) | [trails](trails/) | Cross-chain swap, bridge, and DeFi orchestration via Sequence. Swap tokens across chains, bridge assets, fund a Bankr wallet from any chain, deposit into yield vaults (Aave, Morpho), get token prices, and discover earn pools. Integrates with Bankr submit() for on-chain execution. | | [Alchemy](https://www.alchemy.com) | [alchemy](alchemy/) | Blockchain API access for all supported chains. EVM JSON-RPC, token balances, NFT ownership and metadata, transfer history, token prices, portfolio data, transaction simulation, webhooks, and Solana RPC. Supports API key, x402 pay-per-request (SIWE/SIWS + USDC), and MPP (Tempo/Stripe) access. | +| [APINow](https://apinow.fun) | [apinow](apinow/) | Pay-per-request API marketplace with automatic x402 settlement on Base. Agents use apinow-sdk or CLI to discover endpoints, run workflow pipelines, call external x402 URLs (including Rye commerce probes), use user-factory for LLM endpoints, and generate AI UIs. Works headless with PRIVATE_KEY or with a connected wallet signer (Bankr-compatible). | | [0xWork](https://0xwork.org) | [0xwork](0xwork/) | Decentralized task marketplace on Base. AI agents discover, claim, and complete tasks paid in USDC with on-chain escrow. Supports services, products, and reputation. | | [BOTCOIN](https://botcoin.money) | [BOTCOIN](BOTCOIN/) | Mine BOTCOIN by solving AI-powered hybrid challenges on Base. Stake-gated V2 mining with on-chain reward claims via Bankr. | | [LITCOIN](https://litcoiin.xyz) | [litcoin](litcoin/) | Proof-of-comprehension and proof-of-research mining protocol on Base. AI agents earn $LITCOIN by solving computational problems across 7 domains. Full DeFi stack: staking, vaults, LITCREDIT stablecoin, bounty board, and autonomous agent launchpad. | diff --git a/apinow/SKILL.md b/apinow/SKILL.md new file mode 100644 index 00000000..34762f3e --- /dev/null +++ b/apinow/SKILL.md @@ -0,0 +1,352 @@ +--- +name: apinow +description: >- + Use APINow (apinow-sdk / CLI) to discover, inspect, call, compose, publish, + and monetize pay-per-request APIs on APINow.fun with automatic x402 settlement + on Base. Use for API marketplace discovery, paid endpoint calls, workflow + pipelines, external x402 URLs, LLM endpoint creation via user-factory, AI UI + generation, and agent commerce probes such as Rye checkout intents. Works + headless with PRIVATE_KEY or in apps with a connected wallet signer such as + Bankr-compatible wallets. +metadata: + { + "clawdbot": + { + "emoji": "⚡", + "homepage": "https://apinow.fun", + }, + } +--- + +# APINow - x402 API marketplace, SDK, CLI, workflows, and UI generation + +[APINow.fun](https://apinow.fun) is a pay-per-request API marketplace on [Base](https://base.org) using [x402](https://www.x402.org/). Agents use **`apinow-sdk`** or the **`apinow` CLI** to discover APIs, pay for calls, create and run workflows, proxy external x402 endpoints, create LLM endpoints, and generate sandbox UIs. + +## When to use this skill + +Use this skill when the user wants to: + +- Find an API endpoint by capability, price, schema, namespace, or owner. +- Call a paid APINow endpoint with automatic x402 payment. +- Run or manage a multi-endpoint workflow pipeline. +- Call an external x402 URL through APINow (`discoverPrice`, `callExternal`). +- Create, test, publish, update, version, or delete an APINow endpoint. +- Generate an LLM-backed endpoint from a prompt via user-factory. +- Generate an interactive AI UI for an existing endpoint. +- Integrate APINow into a headless agent, browser app, Bankr wallet flow, or other connected wallet signer. + +Do not use APINow for arbitrary web scraping or non-x402 payments. For external x402 commerce, discover and quote first; only perform final purchase/confirm steps after explicit user approval. + +## Install the skill + +Bankr skill registry install: + +```text +> install the apinow skill from https://github.com/BankrBot/skills/tree/main/apinow +``` + +After installing the skill, install the SDK in the project that will call APINow: + +```bash +npm install apinow-sdk +``` + +Run CLI commands with the package binary: + +```bash +npm exec -- apinow --help +``` + +If `npm exec -- apinow` is unavailable in your package manager, use the local binary directly: `./node_modules/.bin/apinow`. + +## Full system setup + +### Headless agent / server + +Use a funded EVM private key on Base for paid x402 calls and signed write operations. + +```bash +export PRIVATE_KEY=0x... +export APINOW_BASE_URL=https://www.apinow.fun +``` + +`APINOW_BASE_URL` is optional; the production default is `https://apinow.fun` or `https://www.apinow.fun` depending on the SDK version. Set it explicitly in examples and production agents to avoid ambiguity. + +### Browser or connected wallet + +Use `address` + `signer` for signed auth. Paid browser calls require an x402-capable `paidFetch` if the app performs paid calls client-side. + +```typescript +import { createClient } from 'apinow-sdk'; + +const apinow = createClient({ + address, + signer: (message) => walletClient.signMessage({ message }), + baseUrl: 'https://www.apinow.fun', +}); +``` + +### Bankr-style wallet flow + +If the environment exposes a Bankr-compatible signer, wire it through the same `signer(message)` shape. The private key never needs to be passed to browser code. + +```typescript +const apinow = createClient({ + address: bankrWalletAddress, + signer: (message) => bankr.signMessage(message), + baseUrl: 'https://www.apinow.fun', +}); +``` + +## Smoke test + +Before spending money, verify discovery and metadata calls. These are public reads. + +```bash +npm exec -- apinow search "weather" --limit 5 +npm exec -- apinow list --sort newest --limit 5 +npm exec -- apinow info gg402/horoscope +``` + +Then perform one small paid call with a spending cap appropriate for the endpoint. + +```bash +PRIVATE_KEY=0x... npm exec -- apinow call gg402/horoscope \ + --max-cost 0.05 \ + -d '{"sign":"aries"}' +``` + +## Core SDK client + +```typescript +import { createClient } from 'apinow-sdk'; + +const rawPrivateKey = process.env.PRIVATE_KEY; +if (!rawPrivateKey) throw new Error('PRIVATE_KEY is required'); + +const apinow = createClient({ + privateKey: rawPrivateKey.startsWith('0x') + ? (rawPrivateKey as `0x${string}`) + : (`0x${rawPrivateKey}` as `0x${string}`), + baseUrl: process.env.APINOW_BASE_URL ?? 'https://www.apinow.fun', + policy: { + maxPerQueryUsd: 0.25, + maxPerDayUsd: 5, + }, +}); +``` + +## Discover and call endpoints + +Prefer this sequence: `search` -> `info` -> validate schema/price -> `call`. + +```typescript +const matches = await apinow.search('translate text', 5); +const details = await apinow.info('apinowfun', 'translate'); + +const result = await apinow.call('/api/endpoints/apinowfun/translate', { + method: 'POST', + maxCostUsd: 0.05, + body: { + text: 'Hello world', + targetLanguage: 'es', + }, +}); +``` + +CLI equivalent: + +```bash +npm exec -- apinow search "translate text" --limit 5 +npm exec -- apinow info apinowfun/translate +PRIVATE_KEY=0x... npm exec -- apinow call apinowfun/translate \ + --max-cost 0.05 \ + -d '{"text":"Hello world","targetLanguage":"es"}' +``` + +## Workflows + +Workflows chain multiple endpoints into one paid DAG pipeline with payment splitting. Use workflows when the user wants a repeatable multi-step API process rather than one endpoint call. + +```typescript +const workflows = await apinow.listWorkflows({ status: 'active', limit: 10 }); + +const output = await apinow.runWorkflow('f5d40784593aa972', { + query: 'birthday gift ideas for a friend who loves cooking', +}, { + maxCostUsd: 0.50, +}); +``` + +Useful workflow commands: + +```bash +npm exec -- apinow workflows --status active +npm exec -- apinow workflow f5d40784593aa972 +PRIVATE_KEY=0x... npm exec -- apinow run-workflow f5d40784593aa972 \ + --max-cost 0.50 \ + -d '{"query":"gift ideas"}' +``` + +Workflow owners can create versions instead of editing live behavior in-place: + +```typescript +await apinow.createWorkflowVersion('f5d40784593aa972', { + totalPrice: '0.12', + changelog: 'Tune prompt and raise price after usage spike', +}); + +await apinow.setDefaultWorkflowVersion('f5d40784593aa972', 2); +``` + +## External x402 proxy + +Use this for x402 endpoints that are not listed directly on APINow. + +```typescript +const price = await apinow.discoverPrice( + 'https://example.com/x402/profile', + 'POST', +); + +const data = await apinow.callExternal('https://example.com/x402/profile', { + method: 'POST', + body: { handle: 'apinow' }, +}); +``` + +For SDK external calls, set `policy.maxPerQueryUsd` on the client to enforce a default spend ceiling. For CLI external calls, use `--max-cost`. + +CLI: + +```bash +npm exec -- apinow discover https://example.com/x402/profile --method POST +PRIVATE_KEY=0x... npm exec -- apinow call-external https://example.com/x402/profile \ + --method POST \ + --max-cost 0.05 \ + -d '{"handle":"apinow"}' +``` + +### Rye / physical commerce guardrail + +Rye exposes physical checkout intents over x402 at `https://x402.rye.com`. Creating or inspecting a checkout intent can be a safe quote step. Confirming can place a real order. + +Rules for agents: + +- It is OK to create a checkout intent or inspect an existing intent when the user requested a quote. +- Do not call a Rye confirm endpoint unless the user explicitly approves the final product total, taxes, shipping, fees, and destination. +- Do not rely on URL-only discovery for final confirm pricing; use the real intent and body. +- Always pass a conservative `maxCostUsd` / `--max-cost`, or configure `policy.maxPerQueryUsd`, for x402 calls. + +## User-factory: create LLM endpoints + +Use user-factory when the user wants to turn a prompt into a hosted, monetizable API endpoint. + +```typescript +const created = await apinow.factoryPipeline('Score startup pitches on 8 criteria', { + markup: { markupPercent: 30 }, +}); + +console.log(`${created.endpoint.namespace}/${created.endpoint.endpointName}`); +``` + +CLI: + +```bash +PRIVATE_KEY=0x... npm exec -- apinow factory-pipeline \ + "Score startup pitches on 8 criteria" \ + --markup 30 +``` + +## Generate AI UIs + +Use UI generation when the user wants an embeddable or inspectable sandbox frontend for an endpoint. + +```typescript +const details = await apinow.info('gg402', 'horoscope'); + +const ui = await apinow.generateUIAndWait({ + endpointName: details.endpointName, + namespace: details.namespace, + description: details.description, + querySchema: details.querySchema, + responseSchema: details.responseSchema, + examples: details.exampleQuery + ? [{ input: details.exampleQuery, output: details.exampleOutput }] + : undefined, + customPrompt: 'Use a clean dark theme with clear loading and error states', +}); + +if (!ui.source) throw new Error(`UI generation failed: ${ui.errorMessage}`); + +console.log(ui.source['main.ts']); +console.log(ui.source['main.css']); +``` + +CLI: + +```bash +PRIVATE_KEY=0x... npm exec -- apinow ui-generate gg402/horoscope \ + --prompt "clean dark theme with clear loading and error states" +npm exec -- apinow ui-list gg402/horoscope --sort recent +npm exec -- apinow ui-get --source-only +``` + +## Endpoint CRUD + +Use endpoint CRUD only when the user is intentionally publishing or maintaining an API listing. + +Common lifecycle: + +1. Create endpoint config. +2. Test the endpoint with safe inputs. +3. Publish / update metadata and price. +4. Monitor usage and iterate via updates or workflow versions. + +SDK methods include: + +- `createEndpoint(config)` +- `getEndpoint(id)` +- `updateEndpoint(id, updates)` +- `deleteEndpoint(id)` + +All mutating calls require signed auth from `PRIVATE_KEY` or a connected wallet signer. + +## Capability map + +| Goal | SDK / CLI | +|------|-----------| +| Search endpoint catalog | `search`, `listEndpoints`, `apinow search`, `apinow list` | +| Inspect schema, price, wallet | `info`, `apinow info` | +| Pay and call listed endpoint | `call`, `apinow call` | +| Run multi-step pipeline | `runWorkflow`, `apinow run-workflow` | +| Manage workflow versions | `createWorkflowVersion`, `setDefaultWorkflowVersion`, version CLI commands | +| Probe external x402 price | `discoverPrice`, `apinow discover` | +| Pay and call external x402 | `callExternal`, `apinow call-external` | +| Create LLM endpoint | `factoryPipeline`, `factoryCreate`, `apinow factory-*` | +| Generate UI source | `generateUIAndWait`, `apinow ui-*` | +| Publish/manage endpoints | endpoint CRUD SDK methods | + +## Auth and payment model + +- Public reads: `search`, `listEndpoints`, `info`, workflow metadata reads. +- Paid calls: x402 payment is attached automatically by SDK / CLI. +- Writes: SDK signs an auth header with `PRIVATE_KEY` or wallet signer. +- Funding: keep the paying wallet funded with Base USDC or the asset required by the endpoint's x402 terms. +- Spending limits: pass `maxCostUsd` for listed endpoint/workflow SDK calls, configure `policy.maxPerQueryUsd` for client-wide limits, and pass `--max-cost` for CLI paid calls. + +## Operational rules for agents + +- Inspect schemas before calling paid endpoints. +- Ask for confirmation before high-cost calls, physical purchases, irreversible writes, deletes, or publishing monetized endpoints. +- Never print, log, commit, or expose `PRIVATE_KEY`. +- Prefer `APINOW_BASE_URL=https://www.apinow.fun` for production examples. +- For browser apps, never embed private keys; use connected wallet signing. +- Treat generated UI source as untrusted until reviewed before deploying it into an app. +- If a call fails with an x402/payment error, check wallet balance, chain/network, max cost, and endpoint price first. + +## Links + +- [APINow.fun](https://apinow.fun) +- [npm: apinow-sdk](https://www.npmjs.com/package/apinow-sdk) +- [x402](https://www.x402.org/)