API Documentation

Complete reference for integrating Sumplus Arsenal skills into your AI agents.

Overview

Sumplus Arsenal provides a REST API, MCP (Model Context Protocol) interface, and OpenAI-compatible Function Calling for accessing skills programmatically. Skills can be called by any HTTP client or MCP-compatible AI agent.

Base URL

text

https://arsenal.sumplus.xyz

Skill Architecture

Arsenal skills are server-side code executors, not text prompts. Each skill is a TypeScript function that runs on Arsenal's servers — it makes real on-chain RPC calls, invokes protocol SDKs, builds unsigned transactions, and returns structured data back to the agent.

AI Agentreads schema →Skill Schema (DB)knows param names & types

↓ sends request with correct params

AI AgentPOST /api/execute →Skill Executor (Code)runs on Arsenal servers

↓ calls chain RPC / protocol SDK

Blockchain / Protocol

← returns structured result (balances, tx_bytes, positions…)

Two layers, two jobs

Schema (interface contract)

Stored in Supabase. Tells agents what parameters to send and what shape the response will be. This is the only thing an agent reads — it never sees the implementation code.

Executor (implementation)

TypeScript running on Arsenal's servers. Validates input, calls chain RPC nodes or protocol SDKs (Cetus, Bluefin Ember, Jupiter, etc.), and returns ready-to-sign transactions or live on-chain data.

Why code, not text prompts?

✓

Real-time on-chain data

Balances, positions, APYs, pool liquidity — these live on-chain and change every block. Only executable code can fetch them; a text prompt cannot.

✓

Transaction construction

Depositing into a vault requires fetching coin objects, calling a protocol SDK, building a PTB, and serialising it to base64. This is a computation, not a description.

✓

Deterministic validation

Address format, minimum amounts, vault capacity — these are enforced in code before anything touches the chain, so agents always get clean errors, not silent failures.

✓

Credential isolation

RPC keys, SDK credentials, and contract addresses stay server-side in environment variables. Agents receive only the result — never raw secrets.

Division of responsibility: The AI agent decides what to do and assembles the right parameters. Arsenal decides how to do it — handling all blockchain complexity and returning a result the agent can act on immediately.

Authentication

Browsing skills is public. All write and execute endpoints require a Bearer token. Two token types are accepted:

Supabase JWT — from /api/auth/login
API Key — from /api/auth/signup (returned on signup) or /api/auth/apikey — recommended for agents, does not expire

Important: Keep your API keys secret. Never expose them in client-side code or version control.

bash

curl -H 'Authorization: Bearer YOUR_API_KEY' https://arsenal.sumplus.xyz/api/skills

typescript

const res = await fetch('/api/skills', {
  headers: {
    'Authorization': 'Bearer ' + apiKey,
  }
});

REST API

GET/api/skills

List skills with optional filtering, search, and pagination.

Parameter	Type	Description
search	string	Full-text search query
category	string	Filter by category
sort	string	Sort field (e.g. rating_avg.desc)
limit	number	Items per page (default: 20)
offset	number	Pagination offset (default: 0)

bash

curl 'https://arsenal.sumplus.xyz/api/skills?category=Blockchain&limit=10' \
  -H 'Authorization: Bearer YOUR_API_KEY'

GET/api/skills/:id

Get full skill details including schema and ratings.

bash

curl 'https://arsenal.sumplus.xyz/api/skills/SKILL_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

POST/api/execute

Execute a skill with the provided input.

bash

curl -X POST 'https://arsenal.sumplus.xyz/api/execute' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"skill_id": "SKILL_ID", "input": {"address": "0x..."}}'

typescript

const result = await fetch('/api/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    skill_id: 'SKILL_ID',
    input: { address: '0x...' },
  }),
});
const data = await result.json();

Publish Skills

Any authenticated user or agent can publish community skills. New skills start with status: pending and become visible after admin approval. Official skills (author_type: official) are approved immediately.

Required fields

Field	Type	Notes
name	string	1–100 characters
description	string	10–2000 characters
category	string	e.g. Blockchain, Finance, AI/ML
schema	object	{ input: JSONSchema, output: JSONSchema }
tags	string[]	optional
code	string	optional — implementation or pseudocode
usage_examples	array	optional — improves discoverability
is_paid	boolean	default false
price	number	USD per execution; required if is_paid=true

Publish a new skill:

bash

curl -X POST 'https://arsenal.sumplus.xyz/api/skills' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Skill Name",
    "description": "What this skill does, in detail.",
    "category": "Blockchain",
    "tags": ["defi", "ethereum"],
    "version": "1.0.0",
    "schema": {
      "input": {
        "type": "object",
        "properties": {
          "address": { "type": "string", "description": "Wallet address" }
        },
        "required": ["address"]
      },
      "output": {
        "type": "object",
        "properties": {
          "balance": { "type": "string" }
        }
      }
    },
    "code": "// implementation or pseudocode here",
    "usage_examples": [
      {
        "title": "Get balance",
        "input": { "address": "0xabc..." },
        "expected_output": { "balance": "1.5 ETH" }
      }
    ],
    "is_paid": false
  }'

On success, returns { skill: { id, name, status } }. Save the id — you'll need it to update or reference the skill.

Update an existing skill (author or admin only):

bash

curl -X PUT 'https://arsenal.sumplus.xyz/api/skills/SKILL_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Updated description",
    "tags": ["defi", "ethereum", "v2"]
  }'

Agents: Use your API key (from /api/auth/signup or /api/auth/apikey). The author name displayed on your skill comes from your account username — set it at /settings after signing up.

MCP Interface

Full Model Context Protocol support. Three methods: skills/list, skills/get, skills/execute.

Claude Code configuration:

json

{
  "mcpServers": {
    "sumplus": {
      "url": "https://arsenal.sumplus.xyz/mcp",
      "apiKey": "YOUR_API_KEY"
    }
  }
}

List skills:

http

POST /mcp
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "method": "skills/list",
  "params": { "category": "Blockchain", "limit": 10 }
}

Execute a skill:

http

POST /mcp
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "method": "skills/execute",
  "params": {
    "skill_id": "SKILL_ID",
    "input": { "address": "0x..." }
  }
}

Function Calling

Fetch OpenAI-compatible function definitions and pass them directly to any LLM that supports tool use.

Fetch function definitions:

http

GET /api/functions?category=Blockchain
Authorization: Bearer YOUR_API_KEY

# Returns OpenAI-compatible function definitions array

Example function definition returned:

json

{
  "name": "sui_blockchain_toolkit",
  "description": "Interact with the SUI blockchain network",
  "parameters": {
    "type": "object",
    "required": [
      "action",
      "address"
    ],
    "properties": {
      "action": {
        "type": "string",
        "enum": [
          "get_balance",
          "get_tokens",
          "get_nfts"
        ]
      },
      "address": {
        "type": "string",
        "description": "SUI wallet address (0x...)"
      }
    }
  }
}

Execute via POST /api/functions/execute with { "function_name": "sui_blockchain_toolkit", "arguments": { ... } }

Router

The unified router endpoint lets agents search, get, and execute skills through a single API. No skill installation needed — Arsenal acts as the router for all capabilities.

Search:

http

POST /api/router
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "action": "search",
  "query": "SUI blockchain balance"
}

Execute:

http

POST /api/router
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "action": "execute",
  "skill_id": "SKILL_ID",
  "input": { "action": "get_balance", "address": "0x..." }
}

Talus Nexus Gateway

Arsenal wraps a subset of its Sui skills as Talus Nexus off-chain tools so any Nexus DAG workflow can call Arsenal skills as native tool nodes. Each wrapped skill lives at /api/tools/<slug> and exposes the three standard Nexus endpoints: GET /health, GET /meta, POST /invoke.

No API key needed — Nexus Leader nodes authenticate at the application layer via signed HTTP (Ed25519), which is post-MVP. Today the gateway runs un-signed over HTTPS.

Tools advertised for Nexus testnet registration:

FQN	Actions
xyz.sumplus.cetus-testnet@1	get_swap_quote

The testnet tool pins every invocation to Sui testnet and restricts Cetus Aggregator providers to CETUS and DEEPBOOKV3 (the DEXes with live Sui testnet deployments). No mainnet RPC is reachable through it.

Mainnet-only tools (reachable individually, not in batch index):

FQN	Underlying skill
xyz.sumplus.cetus@1	Cetus CLMM
xyz.sumplus.bluefin-ember@1	Bluefin Ember vaults
xyz.sumplus.aftermath@1	Aftermath Finance
xyz.sumplus.navi@1	NAVI Protocol
xyz.sumplus.scallop@1	Scallop

These tools call Sui mainnet RPC. They stay reachable for inspection but are withheld from the batch index to prevent testnet DAGs from accidentally triggering mainnet transactions. Non-Sui skills (EVM / Solana / XLayer / Tempo) are not exposed at all — Talus Nexus only supports Sui today.

Batch index for Nexus CLI --batch:

http

GET /api/tools?network=testnet

# Returns Nexus tools ready for testnet registration
{
  "network": "testnet",
  "tools": [
    { "fqn": "xyz.sumplus.cetus-testnet@1", "url": "https://arsenal.sumplus.xyz/api/tools/cetus-testnet" }
  ]
}

Tool definition (/meta):

http

GET /api/tools/navi/meta

{
  "fqn": "xyz.sumplus.navi@1",
  "type": "offchain",
  "url": "https://arsenal.sumplus.xyz/api/tools/navi",
  "description": "NAVI is the leading lending & borrowing protocol on Sui...",
  "input_schema":  { "$schema": "...", "type": "object", "required": ["action"], "properties": { ... } },
  "output_schema": { "$schema": "...", "oneOf": [ { "properties": { "ok":  { "type": "object" } } },
                                                  { "properties": { "err": { "type": "object" } } } ] }
}

Note: Nexus requires output_schema top-level to be oneOf — DAG edges route off variants.

Invocation (/invoke):

http

POST /api/tools/navi/invoke
Content-Type: application/json

{ "action": "get_markets" }

# → { "ok":  { "protocol": "NAVI Protocol", "markets": [...] } }
# or  { "err": { "reason": "..." } }

Responses always take one of two shapes: { ok: {...} } or { err: { reason: string } }. Both are HTTP 200; only infrastructure errors (unknown slug, malformed JSON) return non-200.

Registering with Talus (operator workflow):

bash

# 1. Local dry-run — no chain effect
nexus tool validate off-chain --url https://arsenal.sumplus.xyz/api/tools/cetus

# 2. Batch registration (requires Sumplus on Talus allowlist)
nexus tool register offchain \
  --url https://arsenal.sumplus.xyz/api/tools \
  --batch \
  --collateral-coin <sui_coin_id>

Tool registration on Talus is currently allowlist-gated during the Nexus beta. Contact the Talus team to be added. Local validate dry-runs work without allowlist access.

Error Codes

Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Invalid input or schema validation failed
401	Unauthorized	Missing or invalid API key
402	Payment Required	Paid skill — payment not verified
403	Forbidden	Insufficient permissions
404	Not Found	Skill not found
500	Server Error	Internal server error