Skip to content
Shonin

For agents and the people who build them

The request is the transaction.

Everything here is a plain HTTP endpoint. There are no accounts and no API keys: an agent pays per call in stablecoins with x402 v2, and settlement only happens when the call succeeds. Every answer says how it was decided, so your agent can gate on it.

Three things every paying agent needs

01 · BEFORE PAYING

Shonin Check

Should my agent pay this? A pre-payment check of any x402 payment request: pay, confirm with a person, or block.

  • pay
  • confirm
  • block
POST /api/v1/check$0.01
How it decides

02 · BEFORE ACTING

Shonin Gate

Execute, confirm or escalate? An approval gate for any agent action, with one confidence bar per risk tier.

  • execute
  • confirm
  • escalate
POST /api/v1/gate$0.01
How it decides

03 · AFTER PAYING

Shonin Receipt

Proof for every agent payment: an on-chain settlement check and a signed, normalized receipt for the books.

  • settled
  • signed
  • no payment found
POST /api/v1/receipt$0.01
How it decides
  1. 01

    Ask

    Call the endpoint like any API.

  2. 02

    402

    The response carries the price: amount, stablecoin, network, payee, and a 5-minute window.

  3. 03

    Sign

    Your agent signs a gasless EIP-3009 transfer authorization. No transaction yet.

  4. 04

    Retry

    Send it in the PAYMENT-SIGNATURE header. We run the job.

  5. 05

    Settle

    Only if the job succeeds does the facilitator settle. Errors are never charged.

More endpoints: decision recipes

Beta$0.010 / call

Triage API

Send a support message, get intent, complexity, frustration, refund intent and a route.

POST /api/v1/triage

{
  "subject": "Duplicate charge",
  "message": "I was charged twice for order A-104. Please refund the duplicate."
}
Beta$0.010 / call

Lead Score API

Score an inbound lead against your own offers: fit, urgency, budget, decision maker, spam.

POST /api/v1/lead-score

{
  "message": "We need a WhatsApp assistant for our 3 restaurants before December. Budget approved.",
  "offers": [
    {
      "slug": "concierge",
      "name": "WhatsApp Concierge",
      "pitch": "An AI assistant that answers customers on WhatsApp"
    },
    {
      "slug": "website",
      "name": "Website",
      "pitch": "A new website"
    }
  ]
}
Beta$0.050 / call

Grant Fit API

Score a grant application against a rubric and get the three sections to fix first.

POST /api/v1/grant-fit

{
  "program": "Ecosystem builder grant",
  "requirements": "Open source; live on mainnet; clear milestones",
  "application": "We are building..."
}
Beta$0.010 / call

Content Gate API

Should this draft ship? Hook, specificity, voice and unsourced-number checks in one call.

POST /api/v1/content-gate

{
  "draft": "Most agents rent a frontier model to return the word 'billing'..."
}
Soon$0.010 / call

Decide API

Typed decisions for agents: Choice, Score and Noul with confidence, in one call, paid per call.

POST /api/v1/decide

Launches only after TypeSafe confirms in writing that its terms allow it. Until then: the recipe APIs, or TypeSafe directly.

{
  "state": {
    "message": "I was charged twice for order A-104. Please refund the duplicate."
  },
  "questions": {
    "team": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payments, refunds, duplicate charges",
        "technical": "Bugs",
        "other": "Anything else"
      }
    },
    "refund": {
      "type": "noul",
      "instructions": "The customer is explicitly asking for a refund"
    }
  }
}
Soon$0.010 / call

Lagos Market Prices API

Daily prices for staples in Lagos markets, sold per query to agents and apps, paid in stablecoins.

GET /api/v1/market-prices

Contributors are paid per verified submission.

{
  "market": "mile-12",
  "item": "rice-50kg"
}

Pay from an agent

With @x402/fetch and a viem account, paying is a wrapped fetch. Cap spend per call on the client, and ask Shonin Check before paying anyone you don't know.

NETWORK
Celo mainnet · eip155:42220
ASSET
USDC · 0xcebA9300f2b948710d2653dD7B07f33A8B32118C
ALSO ACCEPTED
USDT on Celo
PROTOCOL
x402 v2 · exact scheme · PAYMENT-REQUIRED / PAYMENT-SIGNATURE / PAYMENT-RESPONSE
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Holds USDC. No gas token needed: the facilitator submits the transfer.
const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const client = new x402Client().register("eip155:*", new ExactEvmScheme(account));
client.setSpendControls({ maxAmountPerPayment: "$0.10" }); // hard cap per call
const pay = wrapFetchWithPayment(fetch, client);

// Before paying any x402 API, ask Shonin Check ($0.01).
const url = "https://api.example.com/v1/rates";
const first = await fetch(url);
if (first.status === 402) {
  const check = await pay("https://<site>/api/v1/check", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      paymentRequired: first.headers.get("PAYMENT-REQUIRED"),
      url,
      task: "Get today's USD/EUR rate for the invoice",
      budgetUsd: 0.05,
    }),
  });
  const { verdict, reasons } = await check.json(); // "pay" | "confirm" | "block"
  if (verdict !== "pay") throw new Error(`Ask a person first: ${reasons.join("; ")}`);
}
const rates = await pay(url);

Discovery