Sakura MCP API

エージェントまたはウォレットが、ユーザーに代わって意図署名フローを開始する——7 つのプライベートなポリシー値（意図テキスト、ウォレット、ノンス、金額上限、USD 上限、プロトコルビットマップ、アクションビットマップ）が、2 層の Poseidon ツリーを経て 32 バイトのコミットメントに畳み込まれる。sign_intent 命令が Solana に提出され、コミットメントはユーザーのウォレットをシードとする PDA に書き込まれる。戻り値：コミットメントハッシュ、PDA アドレス、sign_intent の tx signature。名目額の 0.1% の一回限り手数料が適用される（統合者の最初の $10M 分はリベート）。

エージェントが、Groth16 証明と束ねた DeFi 動作を提出します——クライアントはローカル（ブラウザの snarkjs、またはバックエンド）で証明を生成し、Sakura MCP サーバーに提出します。サーバーは、execute_with_intent_proof の検証命令と DeFi 命令を、単一の Solana v0 アトミックトランザクションに束ね、メインネットに提出します。同じトランザクション内で Pyth と Switchboard を同時に読み、USD 上限はその中央値で決済され、乖離が 100 bps を超えれば拒絶されます。オンチェーンの alt_bn128 ペアリング検証は約 116k CU、execute 経路全体の実測平均は約 204k CU——証明が通過してはじめて、DeFi 命令は着地します。戻り値：tx signature、action_nonce、keccak256 指紋、双予言機の中央値。

監査人、法律顧問、コンプライアンス機関は、過去の任意のエージェント動作の検証状態を独立に問い合わせることができる。(intent_commitment, action_nonce) あるいは tx signature を与えると、当該動作の ActionRecord PDA の内容——32 バイト意図コミットメント、action_type、target、amount、着地 slot、keccak256 指紋、Groth16 の public inputs、参照した Pyth slot——が返ってくる。公開 verifying key のダウンロードリンクも含まれる（snarkjs による独立な再検証のため）。監査の経路全体が、Sakura の任意のサーバーから独立している。

# Step 1: Discover the current Sakura fee wallet (public, unauthenticated).
#   Any unpaid tools/call returns HTTP 402 with X-Payment-Recipient set.
curl -i -X POST https://www.sakuraaai.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":0,"method":"tools/call","params":{"name":"verify_action"}}' \
  | grep -i "X-Payment-Recipient"
# → X-Payment-Recipient: <SAKURA_FEE_WALLET>   ← send $1.00 USDC here

# Step 2: Transfer $1.00 USDC on mainnet to that address, save the tx signature.

# Step 3: Replay the call, this time with your payment proof.
curl -X POST https://www.sakuraaai.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "x-payment: <YOUR_TX_SIGNATURE>" \
  -H "x-wallet: <YOUR_WALLET_ADDRESS>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "verify_action",
      "arguments": {
        "intent_commitment": "<HEX_32_BYTE_COMMITMENT>",
        "action_nonce": 3
      }
    }
  }'

import { Connection, PublicKey, Transaction } from "@solana/web3.js";
import {
  createTransferCheckedInstruction,
  getAssociatedTokenAddressSync,
} from "@solana/spl-token";

// Canonical mainnet USDC (Circle). On devnet, substitute the test mint
// documented in /testing (7rEhvYrGGT41FQrCt3zNx8Bko9TFVvytYWpP1mqhtLi3).
const USDC_MINT = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";

// Discover the current fee wallet dynamically — an unpaid tools/call
// returns HTTP 402 with the recipient in the X-Payment-Recipient header.
// Never hard-code; the operator may rotate the address without notice.
async function discoverSakuraFeeWallet(): Promise<string> {
  const res = await fetch("https://www.sakuraaai.com/api/mcp", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 0, method: "tools/call",
                          params: { name: "verify_action" } }),
  });
  if (res.status !== 402) throw new Error("Expected HTTP 402 on unpaid call");
  const recipient = res.headers.get("X-Payment-Recipient");
  if (!recipient || recipient === "not-configured")
    throw new Error("Sakura fee wallet not advertised — endpoint misconfigured");
  return recipient;
}

const SAKURA_FEE_WALLET = await discoverSakuraFeeWallet();

async function callSakuraTool(
  toolName: "sign_intent" | "execute_with_proof" | "verify_action",
  params: Record<string, unknown>
) {
  // Build and send the $1.00 USDC x402 payment transaction
  const paymentTx = new Transaction().add(
    createTransferCheckedInstruction(
      senderAta,           // your USDC ATA
      new PublicKey(USDC_MINT),
      sakuraAta,           // Sakura fee wallet USDC ATA
      senderPublicKey,
      1_000_000,           // $1.00 USDC (6 decimals)
      6,
    ),
  );
  const txSig = await connection.sendTransaction(paymentTx, [wallet]);
  await connection.confirmTransaction(txSig);

  // Call the Sakura MCP tool with the payment proof
  const response = await fetch("https://sakura-app.vercel.app/api/mcp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-payment": txSig,
      "x-wallet": senderPublicKey.toString(),
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name: toolName, arguments: params },
    }),
  });

  return response.json();
}

// Example: independently verify a past agent action on-chain
const result = await callSakuraTool("verify_action", {
  intent_commitment: "0x...",
  action_nonce: 3,
});