Masken Docs

Introduction

Masken is an AI-powered summarization network. It uses x402 — the HTTP 402 Payment Required flow — to negotiate, verify, and receipt micropayments per request. Works with Solana (USDC) and optional EVM stablecoins, with verifiable on-chain proofs.

Architecture balances AI inference performance, blockchain verification efficiency, and Web3 payment modularity.


# curl — request summary
curl -X POST https://api.masken.ai/v1/summarize \
  -H "content-type: application/json" \
  -d '{"text":"..."}'
# → HTTP/1.1 402 Payment Required
{ "x402": {
  "receiver": "So1ReceiverPubKey...",
  "amount": 0.05,
  "ttl": 120,
  "nonce": "b64nonce"
}}

Quick Start

Send a request to /v1/summarize. If unpaid, you’ll receive a 402 with x402 metadata.
Pay the invoice on supported chain (e.g., Solana USDC on devnet/mainnet).
Retry the same request adding header x402-proof (see Payments).


// Node.js — handle 402 then retry
import fetch from 'node-fetch';
const r1 = await fetch('https://api.masken.ai/v1/summarize', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ text: '...'  })
});
if(r1.status === 402){
  const meta = await r1.json(); // meta.x402
  // 1) pay on-chain → get signature/txid
  const sig = await pay(meta.x402);
  // 2) retry with x402-proof
  const r2 = await fetch('https://api.masken.ai/v1/summarize', {
    method: 'POST',
    headers:{ 'content-type':'application/json',
      'x402-proof': `sol:${meta.x402.receiver}:${meta.x402.nonce}:${sig}` },
    body: JSON.stringify({ text: '...'  })
  });
}


# curl — retry with proof
curl -X POST https://api.masken.ai/v1/summarize \
  -H "content-type: application/json" \
  -H "x402-proof: sol:ReceiverPubKey:nonce:base64sig" \
  -d '{"text":"Your content here."}'

API

Base URL: https://api.masken.ai

/v1/summarize

POST — Body: { text?: string, url?: string, max_tokens?: number }
Headers: content-type: application/json, optional x402-proof after payment
Responses:
- 200 — { summary, tokens_used, receipt? }
- 402 — { x402: { receiver, amount, ttl, nonce } }


// Express sample: issue 402 when unpaid
app.post('/v1/summarize', async (req,res)=>{
  const paid = await verifyProof(req.headers['x402-proof']);
  if(!paid){
    const invoice = await createInvoice({ amount: 0.05, ttl:120 });
    return res.status(402).json({ x402: invoice });
  }
  const out = await summarize(req.body);
  res.json(out);
});


// Response 200
{ "summary": "...result...",
  "tokens_used": 512,
  "receipt": { "tx": "SigOrTxHash", "chain": "solana" } }

x402 Payments

When unpaid, Masken returns 402 with:

receiver: chain address to receive payment
amount: required amount in currency units (e.g., USDC)
ttl: invoice time-to-live (seconds)
nonce: unique anti-replay token

Retry including header x402-proof:

x402-proof: <kind>:<account>:<nonce>:<base64signature>


// Solana (web3.js) — sign memo w/ nonce
const message = new TextEncoder().encode(nonce);
const signature = await signMessage(message); // Phantom etc.
const proof = `sol:${receiver}:${nonce}:${b64(signature)}`;


// EVM (ethers.js) — optional ERC-20 flow
const sig = await signer.signMessage(nonce);
const proof = `evm:${await signer.getAddress()}:${nonce}:${b64(sig)}`;

Webhooks & Events

Subscribe for async confirmations and receipts.

payment.confirmed — fired when on-chain payment is verified
summary.completed — fired when summarization is ready


// Example webhook payload
{ "type": "payment.confirmed",
  "data": { "invoice": "...", "tx": "SigOrTxHash", "chain": "solana" } }

SDKs

Coinbase x402 SDK — normalize 402 metadata & proofs
Node.js client — thin fetch wrapper + proof helpers
Python client — requests-based helper
Rust (planned) — reqwest client + signer traits


// Node client (pseudo)
import { payAndRetry } from '@masken/client';
const out = await payAndRetry('/v1/summarize', { text:'Hello' });


# Python client (pseudo)
from masken import Client
c = Client(base_url='https://api.masken.ai')
out = c.summarize(text="Hello")

Examples


// Express x402 middleware (simplified)
app.use(async (req,res,next)=>{
  if(req.path !== '/v1/summarize') return next();
  const proof = req.headers['x402-proof'];
  const ok = await verifyProof(proof); // chain + nonce check
  if(!ok){ return res.status(402).json(await createInvoice()); }
  next();
});


// Summarizer (OpenAI or Local LLM)
async function summarize({ text }){
  if(useLocal){
    return localSummarize(text); // HF Transformers
  }
  const r = await openai.chat.completions.create({ ... });
  return { summary: r.choices[0].message.content, tokens_used: r.usage.total_tokens };
}

FAQ

Is a monthly plan required? No. Each request negotiates its own payment via 402.

Which chains? Solana (USDC) first; EVM stablecoins optional.

How do I verify? Use our verifier or Coinbase x402 SDK; submit x402-proof on retry.

Masken Documentation