Documentation

Everything you need to integrate Chart Splat into your application

Quick Start

1. Get your API key

Sign up for free and create an API key from your dashboard.

2. Make your first request

bash
curl -X POST https://api.chartsplat.com/chart \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "bar",
"data": {
"labels": ["Jan", "Feb", "Mar", "Apr"],
"datasets": [{
"label": "Revenue",
"data": [12, 19, 3, 5],
"backgroundColor": "#8b5cf6"
}]
}
}'

3. Use the response

The API returns a base64-encoded PNG image that you can use directly in HTML:

json
{
"image": "data:image/png;base64,iVBORw0KGgo...",
"format": "png",
"width": 800,
"height": 600
}

Chart Types & Examples

Line Chart

{
"type": "line",
"data": {
"labels": ["Jan", "Feb", "Mar", "Apr", "May"],
"datasets": [{
"label": "Sales",
"data": [12, 19, 3, 5, 2],
"borderColor": "#3b82f6",
"fill": false
}]
}
}

Bar Chart

{
"type": "bar",
"data": {
"labels": ["Q1", "Q2", "Q3", "Q4"],
"datasets": [{
"label": "Revenue",
"data": [50, 60, 70, 80],
"backgroundColor": "#10b981"
}]
}
}

Pie Chart

{
"type": "pie",
"data": {
"labels": ["Red", "Blue", "Yellow"],
"datasets": [{
"data": [30, 50, 20],
"backgroundColor": [
"#ef4444", "#3b82f6", "#eab308"
]
}]
}
}

Doughnut Chart

{
"type": "doughnut",
"data": {
"labels": ["Desktop", "Mobile", "Tablet"],
"datasets": [{
"data": [60, 30, 10],
"backgroundColor": [
"#8b5cf6", "#ec4899", "#06b6d4"
]
}]
}
}

Radar Chart

{
"type": "radar",
"data": {
"labels": ["Speed", "Power", "Range", "Durability", "Accuracy"],
"datasets": [{
"label": "Player A",
"data": [65, 59, 90, 81, 56],
"borderColor": "#f59e0b",
"backgroundColor": "rgba(245, 158, 11, 0.2)"
}]
}
}

Polar Area Chart

{
"type": "polarArea",
"data": {
"labels": ["Red", "Green", "Yellow", "Blue"],
"datasets": [{
"data": [11, 16, 7, 14],
"backgroundColor": [
"#ef4444", "#10b981", "#eab308", "#3b82f6"
]
}]
}
}

Candlestick Chart

{
"type": "candlestick",
"data": {
"datasets": [{
"label": "Price",
"data": [
{ "x": "2025-02-25", "o": 4.23, "h": 4.80, "l": 4.10, "c": 4.45 },
{ "x": "2025-02-26", "o": 4.45, "h": 5.50, "l": 4.30, "c": 5.34 },
{ "x": "2025-02-27", "o": 5.34, "h": 6.20, "l": 5.10, "c": 5.97 }
]
}]
}
}

OHLC Chart

{
"type": "ohlc",
"data": {
"datasets": [{
"label": "Price",
"data": [
{ "x": "2025-02-25", "o": 4.23, "h": 4.80, "l": 4.10, "c": 4.45 },
{ "x": "2025-02-26", "o": 4.45, "h": 5.50, "l": 4.30, "c": 5.34 },
{ "x": "2025-02-27", "o": 5.34, "h": 6.20, "l": 5.10, "c": 5.97 }
]
}]
}
}

Official SDK

Install the npm package

bash
npm install chartsplat

TypeScript / JavaScript

typescript
import { ChartSplat } from 'chartsplat';
const client = new ChartSplat('YOUR_API_KEY');
// Generate a bar chart
const chart = await client.generateChart({
type: 'bar',
data: {
labels: ['Jan', 'Feb', 'Mar', 'Apr'],
datasets: [{
label: 'Revenue',
data: [12, 19, 3, 5],
backgroundColor: '#8b5cf6'
}]
}
});
// Use the image
console.log(chart.image); // data:image/png;base64,...
// Or save to file (Node.js)
import fs from 'fs';
const base64Data = chart.image.replace(/^data:image\/png;base64,/, '');
fs.writeFileSync('chart.png', Buffer.from(base64Data, 'base64'));

React Example

tsx
import { ChartSplat } from 'chartsplat';
import { useState, useEffect } from 'react';
const client = new ChartSplat('YOUR_API_KEY');
function MyChart() {
const [chartUrl, setChartUrl] = useState<string | null>(null);
useEffect(() => {
async function loadChart() {
const chart = await client.generateChart({
type: 'line',
data: {
labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
datasets: [{
label: 'Visitors',
data: [100, 200, 150, 300, 250],
borderColor: '#ec4899'
}]
}
});
setChartUrl(chart.image);
}
loadChart();
}, []);
if (!chartUrl) return <div>Loading...</div>;
return <img src={chartUrl} alt="Chart" />;
}

OpenAPI Specification

We provide a complete OpenAPI 3.1 specification that you can use to generate clients in any language.

Download OpenAPI Spec

Generate Clients with OpenAPI Generator

Use OpenAPI Generator to create clients for 50+ languages:

Python

bash
npx @openapitools/openapi-generator-cli generate -i https://chartsplat.com/openapi.yaml -g python -o ./chartsplat-python

Go

bash
npx @openapitools/openapi-generator-cli generate -i https://chartsplat.com/openapi.yaml -g go -o ./chartsplat-go

Java

bash
npx @openapitools/openapi-generator-cli generate -i https://chartsplat.com/openapi.yaml -g java -o ./chartsplat-java

Ruby

bash
npx @openapitools/openapi-generator-cli generate -i https://chartsplat.com/openapi.yaml -g ruby -o ./chartsplat-ruby

Other Tools

CLI Tool

Generate charts from your terminal. Perfect for scripting, automation, and quick visualizations.

Install

bash
npm install -g chartsplat-cli

Set API Key

bash
export CHARTSPLAT_API_KEY=your-api-key-here

Quick Examples

Bar Chart

bash
chartsplat bar -l "Q1,Q2,Q3,Q4" -d "50,75,60,90" -o chart.png

Line Chart with Title

bash
chartsplat line -l "Mon,Tue,Wed,Thu,Fri" -d "5,9,3,7,2" --title "Weekly Traffic" -o traffic.png

Pie Chart with Color

bash
chartsplat pie -l "Apple,Samsung,Other" -d "40,30,30" -c "#8b5cf6" -o market.png

Options

OptionDescription
-l, --labelsComma-separated labels
-d, --dataComma-separated values
-t, --titleChart title
-c, --colorBackground color (hex)
-w, --widthImage width (default: 800)
--heightImage height (default: 600)
-o, --outputOutput file path
--configJSON config file

Config Files

For complex charts with multiple datasets, use a config file:

bash
chartsplat init -o my-chart.json
# Edit the file, then:
chartsplat bar --config my-chart.json -o output.png

x402 Payments

Chart Splat accepts x402 micropayments as an alternative to API key authentication. Pay ~$0.005 USDC per chart on Base mainnet — no account, no API key, no subscription. Ideal for AI agents and one-off users.

How it works

x402 uses the HTTP 402 Payment Required status to negotiate payment off-chain. The buyer signs an EIP-3009 authorization; a facilitator settles on-chain and pays the gas. The buyer never sends an on-chain transaction directly.

  1. Client sends POST /chart with no API key
  2. Server returns 402 with payment requirements
  3. Client signs an EIP-3009 authorization off-chain
  4. Client retries with the signed payment header
  5. Server settles via the Coinbase facilitator and returns the chart + a settlement transaction hash

Quick start (TypeScript)

Use @x402/fetch to wrap the standard fetch — it handles the full 402-then-pay-then-retry flow automatically.

bash
npm install @x402/fetch @x402/evm @x402/core viem
typescript
import { wrapFetchWithPayment, x402Client } from '@x402/fetch';
import { registerExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';
const account = privateKeyToAccount(process.env.X402_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const res = await fetchWithPayment('https://api.chartsplat.com/chart', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
type: 'bar',
data: {
labels: ['Q1', 'Q2', 'Q3', 'Q4'],
datasets: [{ label: 'Revenue', data: [50, 75, 60, 90] }],
},
}),
});
const { image } = await res.json();
// image is a base64-encoded PNG (data:image/png;base64,...)
// Settlement proof
const settlement = res.headers.get('PAYMENT-RESPONSE');
if (settlement) {
const { transaction } = JSON.parse(atob(settlement));
console.log(`Paid: https://basescan.org/tx/${transaction}`);
}

Pay with the Agentic Wallet CLI (awal)

Coinbase's Agentic Wallet CLI manages the wallet and pays the 402 for you — no raw private keys. It's what agents arriving from Agentic.Market already use.

bash
npx awal x402 pay "https://api.chartsplat.com/chart" \
--method POST \
--data '{"type":"bar","data":{"labels":["Q1","Q2","Q3","Q4"],"datasets":[{"label":"Revenue","data":[50,75,60,90]}]}}'

Supported networks

NetworkChain IDTokenUse For
Baseeip155:8453USDCProduction
Base Sepoliaeip155:84532USDC (testnet)Testing

Get test USDC for Base Sepolia from the Circle faucet.

Protocol headers

HeaderDirectionContains
PAYMENT-REQUIREDServer → ClientBase64 payment requirements (price, network, payTo)
PAYMENT-SIGNATUREClient → ServerBase64 signed EIP-3009 authorization
PAYMENT-RESPONSEServer → ClientBase64 settlement result (tx hash, network, payer)

Use the v2 packages

Install the scoped @x402/* packages (v2.x). The legacy unscoped [email protected] uses older header names and will not interop with this server.

Learn more

AI & Agents

Chart Splat is agent-native. Install the Chart Splat skill from ClawHub to give any OpenClaw agent the ability to generate charts from natural language. An MCP server is also available for Claude, Codex, and compatible editors.

OpenClaw Quick Start

Install the Chart Splat skill from ClawHub and start generating charts in seconds.

Install from ClawHub

bash
openclaw skills install bobbyg603/chart-splat

Or install with npx:

bash
npx openclaw skills install bobbyg603/chart-splat

Configure API Key

Add your Chart Splat API key to ~/.openclaw/openclaw.json:

json
{
"skills": {
"bobbyg603/chart-splat": {
"env": {
"CHARTSPLAT_API_KEY": "your-api-key-here"
}
}
}
}

Try It

bash
openclaw "Create a bar chart of quarterly revenue: Q1=$50k, Q2=$75k, Q3=$60k, Q4=$90k"

Pay-per-chart with x402 (no API key)

For agents that hold an EVM wallet but don't want to manage an API key or subscription, install the chartsplat-x402 skill instead. It pays ~$0.005 USDC per chart on Base mainnet via x402. No signup, no key, no rate limit ledger to track.

Install from ClawHub

bash
openclaw skills install bobbyg603/chartsplat-x402

Configure your wallet

Add your wallet's private key to ~/.openclaw/openclaw.json:

json
{
"skills": {
"bobbyg603/chartsplat-x402": {
"env": {
"X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
}
}
}
}

The wallet needs a small USDC balance on Base mainnet (~$0.05 covers ten charts). The buyer never sends an on-chain transaction — the Coinbase facilitator settles and pays gas.

Tip: You can have both chart-splat and chartsplat-x402 installed side by side. The agent picks based on whether you have an API key or a wallet configured. See the x402 Payments section for protocol detail.

MCP Server Setup (Claude, Codex & Editors)

The Model Context Protocol (MCP) is an open standard that lets AI tools like Claude, Codex, Cursor, and VS Code call Chart Splat as a native tool. Install the MCP server with zero configuration:

Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

json
{
"mcpServers": {
"chartsplat": {
"command": "npx",
"args": ["-y", "chartsplat-mcp"],
"env": {
"CHARTSPLAT_API_KEY": "your-api-key-here"
}
}
}
}

Claude Code

Add Chart Splat to your Claude Code project:

bash
claude mcp add chartsplat -- npx -y chartsplat-mcp
# Then set your API key in the environment:
export CHARTSPLAT_API_KEY="your-api-key-here"

Available MCP Tools

ToolDescription
generate_chartGenerate any chart type with full configuration
line_chartQuick line chart from labels and values
bar_chartQuick bar chart from labels and values
pie_chartQuick pie chart from labels and values
doughnut_chartQuick doughnut chart from labels and values
radar_chartQuick radar chart from labels and values
candlestick_chartFinancial candlestick chart from OHLC data
ohlc_chartOHLC bar-style chart from financial data

Example Prompts for Agents

These prompts work with any agent that has Chart Splat configured (OpenClaw skill or MCP):

Simple chart

“Create a bar chart showing quarterly revenue: Q1=$50k, Q2=$75k, Q3=$60k, Q4=$90k”

Multi-series comparison

“Make a line chart comparing 2024 vs 2025 monthly sales. 2024: [12, 19, 3, 5, 2, 14, 8, 11, 15, 20, 18, 22]. 2025: [15, 22, 8, 12, 6, 18, 11, 14, 19, 25, 21, 28].”

Pie breakdown

“Generate a pie chart of our traffic sources: Organic 45%, Paid 25%, Social 20%, Referral 10%”

From data analysis

“Analyze this CSV data and create a chart that best visualizes the trend”

Radar skill comparison

“Create a radar chart comparing two candidates. Alice: Communication 9, Technical 7, Leadership 8, Creativity 6, Teamwork 9. Bob: Communication 6, Technical 9, Leadership 7, Creativity 8, Teamwork 7.”

Best Practices

1

Be specific with data

Provide exact numbers and labels in your prompts. Agents produce better charts when the data is unambiguous rather than described vaguely.

2

Choose the right chart type

Use line charts for trends over time, bar charts for comparisons, pie/doughnut for proportions, and radar for multi-dimensional comparisons.

3

Handle the response

The API returns a base64 data URI. Save it to a file, embed it in HTML, or pass it back to the user. OpenClaw handles output automatically via the CLI, and MCP does the same for compatible editors.

4

Respect rate limits

Check X-RateLimit-Remaining headers in your agent logic. The free tier allows 100 requests/month. Upgrade for higher limits.

5

Keep API keys secure

Store your API key in environment variables, not in code. For OpenClaw, use the ~/.openclaw/openclaw.json config file. For MCP, use the env field in the server config.

API Reference

POST/chart

Headers

HeaderRequiredDescription
X-Api-KeyYes*YOUR_API_KEY (recommended)
AuthorizationYes*Bearer YOUR_API_KEY (alternative)
Content-TypeYesapplication/json

* Use either Authorization or X-Api-Key, not both

Request Body

FieldTypeDefaultDescription
typestring"line"Chart type: line, bar, pie, doughnut, radar, polarArea
data.labelsstring[]-Labels for X-axis or segments (required)
data.datasetsarray-Array of datasets (required)
options.widthnumber800Image width in pixels
options.heightnumber600Image height in pixels

Response Headers

HeaderDescription
X-RateLimit-LimitYour monthly request limit
X-RateLimit-RemainingRequests remaining this month
X-RateLimit-ResetWhen the limit resets (ISO 8601)

Rate Limits

PlanRequests/MonthAPI Keys
Free1001
Pro10,0005
EnterpriseUnlimitedUnlimited

When you exceed your rate limit, the API returns a 429 status code.Upgrade your plan for higher limits.

Need Help?

Have questions or need assistance? Fill out the form below and we'll get back to you as soon as possible.