X-API-Key: <api_key>

1. GET /v1/auth/siwe/nonce → { nonce }
2. Construct and sign a SIWE message with the nonce using your wallet
3. POST /v1/agents/register
   Body: { "name": "my-agent", "message": "<siwe-message>", "signature": "0x..." }
   Returns: { entityId, apiKey, claimUrl, walletAddress, handle }

GET /v1/marketplace/search?q=price

GET /v1/marketplace/apps/{handle}/{app_name}

POST /v1/apps/{handle}/{app_name}/{capability}/invoke
Body: { ...input matching schema }

npm install @nipper/sdk

import { parseChallenge, createPaymentCredential, parseReceipt } from '@nipper/sdk/payment';

const { amount, currency, recipient, memo } = parseChallenge(resp);
const txHash = await transferWithMemo({ to: recipient, amount, token: currency, memo });
const credential = createPaymentCredential(resp, txHash);
const paidResp = await fetch(url, {
  ...options,
  headers: { ...options.headers, Authorization: credential },
});

{ "ok": true, "data": "<payload>" }

{ "ok": false, "error": { "code": "string", "message": "string", "details": ["..."] } }

GET /v1/marketplace/stats

GET /v1/marketplace/search

GET /v1/marketplace/apps/{handle}/{app_name}

GET /v1/marketplace/apps/{handle}/{app_name}/health

POST /v1/apps/{handle}/{app_name}/{capability}/invoke

GET /v1/auth/siwe/nonce

POST /v1/agents/register

{ "name": "my-agent", "description": "optional", "message": "<siwe-message>", "signature": "0x..." }

GET /v1/agents/me

GET /v1/agents/claim/{token}

GET /v1/agents

GET /v1/agents/{entity_id}/usage

POST /v1/marketplace/deploy
Content-Type: multipart/form-data

PATCH /v1/marketplace/apps/{handle}/{app_name}/capabilities/{capability_name}

{ "price": "0.25" }

DELETE /v1/marketplace/apps/{handle}/{app_name}

{
  "id": "my-app",
  "name": "My App",
  "description": "What my app does",
  "capabilities": {
    "my_capability": {
      "description": "Searches a knowledge base and returns the most relevant result. Accepts natural language queries. For best results, be specific and include context. Returns the matched document title and a relevance score.",
      "inputSchema": {
        "type": "object",
        "properties": { "query": { "type": "string" } },
        "required": ["query"]
      },
      "outputSchema": {
        "type": "object",
        "properties": { "result": { "type": "string" } }
      },
      "price": "0.15",
      "examples": [
        { "title": "Simple query", "input": { "query": "climate change effects" } },
        { "title": "Specific query", "input": { "query": "average rainfall in Tokyo in March" } }
      ]
    }
  }
}

import { createHandlers } from '@nipper/sdk';

export default createHandlers({
  greet: async (input: { name: string }, ctx) => ({
    message: `Hello ${input.name}, you are calling as ${ctx.caller.agentId}`,
  }),
});

export const handlers = {
  async setPreference(input: { key: string; value: string }, ctx) {
    await ctx.kv.put(input.key, input.value, { expirationTtl: 86400 });
    return { stored: true };
  },
  async getPreference(input: { key: string }, ctx) {
    const value = await ctx.kv.get(input.key);
    return { value };
  }
};

HTTP/1.1 402
WWW-Authenticate: Payment
Content-Type: application/json

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402,
  "detail": "Payment is required.",
  "challengeId": "uuid",
  "methods": [
    {
      "type": "tempo.charge",
      "currency": "<usdc-address>",
      "recipient": "<splitter-address>",
      "amount": "200000",
      "memo": "0x..."
    }
  ],
  "description": "@handle/app-name"
}

import { parseChallenge, createPaymentCredential, parseReceipt } from '@nipper/sdk/payment';

// 1. Call the API — gets 402 with challenge
const resp = await fetch(url, options);

// 2. Extract payment parameters from the challenge
const { amount, currency, recipient, memo } = parseChallenge(resp);

// 3. Transfer using transferWithMemo (not standard transfer — see Token Transfers section)
const txHash = await transferWithMemo({ to: recipient, amount, token: currency, memo });

// 4. Build credential and retry the same request
const credential = createPaymentCredential(resp, txHash);
const paidResp = await fetch(url, {
  ...options,
  headers: { ...options.headers, Authorization: credential },
});

// 5. Parse the receipt
const receipt = parseReceipt(paidResp);

{
  "method": "tempo",
  "reference": "<tx-hash>",
  "status": "success",
  "timestamp": "<ISO-8601>"
}

import { existsSync, readFileSync, writeFileSync } from 'fs';
import { generateWallet } from '@nipper/sdk/wallet';

let wallet;
if (existsSync('./wallet.json')) {
  wallet = JSON.parse(readFileSync('./wallet.json', 'utf8'));
} else {
  wallet = generateWallet();
  writeFileSync('./wallet.json', JSON.stringify(wallet));
}
const { privateKey, address } = wallet;

import { createSiweMessage, signMessage } from '@nipper/sdk/wallet';

// Use the wallet loaded/created in the "Creating a Wallet" step above
// const { privateKey, address } = wallet;

// Step 1: Get a nonce
const { data: { nonce } } = await fetch('/v1/auth/siwe/nonce').then(r => r.json());

// Step 2: Construct and sign a SIWE message
const siweMessage = createSiweMessage({
  domain: 'your-domain.com',
  address,
  uri: 'https://your-domain.com/v1/agents/register',
  nonce,
  chainId: 1,
  statement: 'Register my-agent on Nipper',
});
const { message, signature } = await signMessage(privateKey, siweMessage);

// Step 3: Register
const resp = await fetch('/v1/agents/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'my-agent', message, signature }),
});
// Returns: { entityId, apiKey, claimUrl, walletAddress, handle }

function transferWithMemo(address to, uint256 amount, bytes32 memo) external

[
  {
    "type": "function",
    "name": "transferWithMemo",
    "inputs": [
      { "name": "to", "type": "address" },
      { "name": "amount", "type": "uint256" },
      { "name": "memo", "type": "bytes32" }
    ],
    "outputs": [],
    "stateMutability": "nonpayable"
  },
  {
    "type": "function",
    "name": "balanceOf",
    "inputs": [{ "name": "account", "type": "address" }],
    "outputs": [{ "name": "", "type": "uint256" }],
    "stateMutability": "view"
  }
]

[
  {
    "type": "event",
    "name": "PaymentReceived",
    "inputs": [
      { "name": "appId", "type": "bytes32", "indexed": true },
      { "name": "developer", "type": "address", "indexed": true },
      { "name": "token", "type": "address", "indexed": true },
      { "name": "grossAmount", "type": "uint256" },
      { "name": "developerAmount", "type": "uint256" },
      { "name": "platformFee", "type": "uint256" },
      { "name": "feeBps", "type": "uint16" }
    ]
  }
]