getting started

What is Enigma?

devnet live v0.1 solana · usdc

Enigma is a non-custodial API billing platform built on Solana. It turns any HTTP endpoint into a paid product in about three minutes — with zero code changes to your upstream service.

If you've built an API and want to charge for it, Enigma handles everything: authentication, per-request metering, USDC settlement, and revenue collection. Payment lands directly in a program-derived account (PDA) that only you control — Enigma never touches your funds.

How it works

Enigma sits between callers and your real API as a smart proxy. On every request:

01

caller authenticates & pays

The caller sends a payment authorization alongside the HTTP request. Enigma validates it before forwarding anything upstream.

02

proxy meters & settles on Solana

Enigma submits an on-chain transaction, crediting the developer's PDA vault with USDC. Sub-second finality means this completes within the request lifecycle.

03

upstream response forwarded

The caller receives your API's response. Your revenue sits in your PDA, ready to sweep anytime. No invoicing. No waiting.

Key concepts

concept	what it means
`proxy url`	Your metered endpoint. Format: `<your-enigma-host>/{user}/{api}` — share with callers. The current devnet deployment is hosted at `enigma-production-efad.up.railway.app`; a stable mainnet domain is TBD.
`pda vault`	A program-derived USDC token account on Solana, seeded by your wallet. Only you can sweep it.
`upstream url`	Your real API. Enigma forwards requests here after payment is confirmed. Never exposed to callers.
`price / request`	USDC amount a caller pays per proxied request. Set by you, stored on-chain, changeable anytime.
`collect_balance`	The on-chain instruction that sweeps your PDA revenue to your wallet, minus the platform fee.

Non-custodial guarantee — Enigma never holds your money. Even if we disappear tomorrow, your PDA balance remains recoverable on-chain through the program directly.

getting started

Quick Start

Zero to a paid API in under five minutes.

01

sign in to the dashboard

Open the app and connect a Solana wallet (Phantom or Solflare) or sign in with email OTP. Your on-chain user account is initialized automatically on first registration; the wallet pays a small Solana rent deposit for the PDA vault.

02

register & price your API

In the dashboard, click + new api. Enter a name (this becomes part of your proxy URL), the upstream URL Enigma should forward to, and a per-request price in USDC. Set 0 for free-but-metered.

03

share your proxy URL & earn

That's it. The dashboard shows your proxy URL: <your-host>/{username}/{api-name}. Callers pay on every request, you earn automatically. Revenue accrues in your PDA vault — claim it from the dashboard's earnings card whenever you like.

04

SDK roadmap

A first-party SDK (JS, Python, Rust, Go) is planned for v0.2 so you can register and manage APIs from code. The snippet below previews the planned ergonomics — none of these packages resolve yet.

javascript (planned)

import { Enigma } from '@enigma-sh/sdk';

const client = new Enigma({ privateKey: process.env.ENIGMA_PRIVATE_KEY });

const api = await client.register({
  name:            'weather',
  upstream:        'https://weather-service.api.com',
  pricePerRequest: 0.005,   // $0.005 USDC per call
  description:     'Real-time weather data',
});

console.log(api.proxyUrl);

01

fund a Solana wallet with USDC

You need a Solana keypair and devnet (or mainnet) USDC. See Wallet & USDC Setup for a step-by-step guide if you're new to Solana.

02

use the x402 payment protocol

Enigma authenticates callers via the x402 payment protocol, not API keys. Your client signs a payment payload for each request; the proxy validates and settles it on Solana before forwarding upstream. A first call without payment returns 402 Payment Required with the price tag.

03

call any Enigma-proxied API

The reference implementation lives at demo/call.mjs in the repo. Drop in your buyer wallet's base58 secret and you're ready to call paid endpoints:

javascript (node)

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactSvmScheme } from '@x402/svm/exact/client';
import { createKeyPairSignerFromBytes } from '@solana/kit';
import { base58 } from '@scure/base';

const signer = await createKeyPairSignerFromBytes(base58.decode(process.env.BUYER_SECRET_B58));

const fetchWithPayment = wrapFetchWithPaymentFromConfig(globalThis.fetch, {
  schemes: [{ network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
              client:  new ExactSvmScheme(signer) }],
});

const res = await fetchWithPayment('https://<host>/alice/weather/v1/now?city=NYC');
const data = await res.json();
console.log(data);                       // upstream response
console.log(res.headers.get('PAYMENT-RESPONSE')); // settlement info

for providers

Register an API

Register any HTTP endpoint as a paid, metered API. No code changes to your upstream required.

Prerequisites

✓ A Solana wallet (Phantom or Solflare) or email OTP account
✓ ~0.005 SOL for transaction fees and PDA rent
✓ A publicly reachable HTTP endpoint (or tunneled via ngrok, cloudflare tunnel, etc.)

Via the dashboard

01

sign in to the dashboard

Connect your wallet or use email OTP. Registering your first API creates your PDA vault on-chain automatically.

02

click "Register API"

Enter a name (used in your proxy URL) and your upstream base URL. The name forms a permanent part of your proxy address — choose carefully.

03

set a price per request

Enter a USDC amount. Set 0 for a free but metered API — useful for analytics or gating before a paid launch.

04

copy your proxy URL

Your endpoint is live at <your-host>/{username}/{api-name}. All sub-paths forward verbatim: /alice/weather/v1/now → upstream.url/v1/now.

Via the SDK roadmap

Not yet shipped. The Enigma SDK is on the v0.2 roadmap. Until then, register APIs through the dashboard or hit the HTTP endpoints directly (see API Reference → Endpoints). The snippet below previews the planned shape.

javascript (planned)

const api = await client.register({
  name:            'my-api',        // → <host>/you/my-api
  upstream:        'https://…',
  pricePerRequest: 0.01,           // USDC. 0 = free+metered
  description:     'What your API does',
});

// update price anytime — takes effect immediately
await client.api('my-api').setPrice(0.005);

// pause / resume
await client.api('my-api').disable();
await client.api('my-api').enable();

API names are permanent. The name in your proxy URL cannot be changed after registration. All on-chain state is seeded from it.

for providers

Pricing & Fees

You set the price. Enigma takes a small platform fee at collection time. Everything else goes directly to your wallet.

Platform fee structure

parameter	value	note
`platform_fee_bps`	1000 bps (10%)	Currently 1000 bps; lives in the on-chain global config and is adjustable via `update_global_config`. Deducted at collect time, not per-request.
`minimum_price`	0 USDC	Free APIs are supported — pure metering with no fee taken
`fee_destination`	Enigma platform vault	Split happens atomically in `collect_balance` on-chain
`payout_latency`	~400ms	Solana finality. Collect whenever you want.

Example: You charge $0.01/request. 1,000 calls = $10.00 in your PDA. On collect: you receive $9.00 USDC, Enigma receives $1.00.

Changing your price

Price changes are instant — the next request is billed at the new rate. There is no migration, no notice period required.

javascript

await client.api('weather').setPrice(0.001); // $0.001/req, effective immediately

for providers

Collecting Revenue

Your earnings accumulate in a Solana PDA vault. Sweep to your wallet at any time.

From the dashboard

Open the dashboard and find the earnings card. It shows your live PDA balance; click claim to invoke collect_balance on-chain. The wallet you're signed in with signs the transaction; the platform fee (currently 10%) goes to Enigma's vault and the remainder lands in your wallet's USDC associated token account — atomically, in one transaction.

From code

The dashboard's claim button is a thin wrapper around the on-chain instruction. For headless use, build the same transaction yourself using the program ID below and submit it via any Solana RPC. The reference implementation is at ui/lib/enigma-program.ts (function buildCollectBalanceTransaction) — it derives your PDA and ATA, constructs the collect_balance instruction, and returns a signable transaction.

Planned SDK ergonomics roadmap

javascript (planned)

// check your PDA balance
const { usdc } = await client.balance();
console.log(usdc); // → 142.50

// sweep to your wallet (net of 10% platform fee)
const tx = await client.collect();
console.log(tx.signature); // solana tx hash
console.log(tx.received);  // → 128.25 USDC sent to your wallet

No minimum balance is required — collect after one request or a thousand.

for callers

Buyer Guide

Calling an Enigma-proxied API is nearly identical to calling the upstream directly — point your client at the proxy URL and let an x402 helper sign each request from your Solana wallet.

URL pattern

pattern

https://<your-host>/{username}/{api-name}/{path}

Everything after the API name is forwarded verbatim — query params, headers, body, and HTTP method all pass through unchanged.

With curl (no payment)

A bare curl hits the proxy but returns 402 Payment Required with a JSON price tag in the body. The buyer must satisfy x402 to receive the upstream response:

shell

$ curl -i https://<host>/alice/weather/v1/now
# HTTP/1.1 402 Payment Required
# body: { "scheme": "exact", "network": "solana:…", "payTo": "<pda>", "amount": 5000 }

With an x402 client

Use a Solana-aware x402 client (e.g. @x402/fetch + @x402/svm) to sign payment payloads automatically. The full working example lives at demo/call.mjs.

javascript (node)

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
              client:  new ExactSvmScheme(signer) }],
});

const res = await fetchWithPayment('https://<host>/alice/weather/v1/forecast', {
  method:  'POST',
  headers: { 'Content-Type': 'application/json' },
  body:    JSON.stringify({ city: 'NYC', days: 7 }),
});

const data = await res.json();
console.log(res.headers.get('PAYMENT-RESPONSE')); // settlement signature + amount

Agent & script usage roadmap

Today, agents sign each x402 payment with a Solana keypair — no wallet pop-up, no per-call human interaction (see demo/call.mjs). A session-level spend authorization is on the roadmap so an agent can declare an upper bound up front and avoid signing each payload individually:

javascript (planned)

// authorize a spend limit for this session (planned)
await client.authorize({ maxSpend: 10.00, expiresIn: '1h' });

// subsequent calls draw from the authorization automatically
const r1 = await client.call('alice/weather', { path: '/v1/now' });
const r2 = await client.call('bob/geocode',   { path: '/v1/ip'  });

for callers

Wallet & USDC Setup

Enigma settles in USDC on Solana. Here's how to get set up if you're new to the ecosystem.

Option A — Self-custody (recommended)

01

install a Solana wallet

Phantom (phantom.app) and Solflare (solflare.com) are wired into the dashboard today. Any wallet that exposes the Solana wallet-adapter standard should work; support for more wallets is on the roadmap.

02

get USDC on Solana

Buy SOL on Coinbase, Kraken, or Binance, then swap to USDC via Jupiter (jup.ag). Alternatively, bridge USDC from Ethereum using Wormhole or Circle's CCTP.

03

connect to Enigma

Open the dashboard, click sign in, choose your wallet, and approve the connection. The first time you register an API, a small on-chain transaction initializes your user account (PDA + USDC ATA) — a one-time setup cost.

Option B — Email OTP

Sign in with an email address — no wallet required. Enigma creates a Solana account for you. Transfer USDC from an external wallet to fund it.

Note: Email OTP accounts are custodial in v0.1. For production use or large balances, connect your own wallet for full self-custody.

sdk

Installation roadmap

The Enigma SDK is in design — JavaScript / TypeScript, Python, Rust, and Go are planned for v0.2 on a single release cadence. None of the package commands below resolve yet. They preview the planned ergonomics.

Until the SDK ships: Use the dashboard to register and manage APIs. For programmatic access, hit the HTTP endpoints directly (see Endpoints) and use any x402-compatible Solana client (e.g. @x402/fetch — see demo/call.mjs) for buyer-side calls.

terminal

$ npm install @enigma-sh/sdk
# or
$ bun add @enigma-sh/sdk
$ pnpm add @enigma-sh/sdk

Requires Node 18+ or Bun 1+. Full TypeScript types included.

terminal

$ pip install enigma-sdk
# or
$ poetry add enigma-sdk
$ uv add enigma-sdk

Requires Python 3.10+. Async-first via asyncio; sync wrappers available.

Cargo.toml

[dependencies]
enigma-sdk = "0.1"
tokio      = { version = "1", features = ["full"] }

Async-native with Tokio. MSRV: Rust 1.75.

terminal

$ go get github.com/enigma-sh/sdk-go@latest

Requires Go 1.22+. Context-aware; all calls accept context.Context.

sdk

Provider SDK roadmap

For API providers — registering endpoints, managing pricing, and collecting revenue. Planned shape; not yet released.

javascript

import { Enigma } from '@enigma-sh/sdk';

const client = new Enigma({ privateKey: process.env.ENIGMA_PRIVATE_KEY });

// register
const api = await client.register({ name: 'my-api', upstream: 'https://…', pricePerRequest: 0.01 });

// list all your APIs
const apis = await client.apis();

// update price
await client.api('my-api').setPrice(0.005);

// disable / enable
await client.api('my-api').disable();

// check balance
const { usdc } = await client.balance();

// collect to your wallet
const tx = await client.collect();

python

from enigma import Enigma
import os

client = Enigma(private_key=os.environ["ENIGMA_PRIVATE_KEY"])

# register
api = await client.register(name="my-api", upstream="https://…", price_per_request=0.01)

# update price
await client.api("my-api").set_price(0.005)

# collect
balance = await client.balance()  # → { 'usdc': 142.5 }
tx      = await client.collect()

rust

use enigma_sdk::{Enigma, RegisterOptions};

let client = Enigma::new(&private_key);

// register
let api = client.register(RegisterOptions {
    name:              "my-api".into(),
    upstream:          "https://…".into(),
    price_per_request: 0.01,
    ..Default::default()
}).await?;

// collect
let balance = client.balance().await?;
let tx      = client.collect().await?;

go

import (
    enigma "github.com/enigma-sh/sdk-go"
    "os"
)

client := enigma.New(os.Getenv("ENIGMA_PRIVATE_KEY"))

// register
api, err := client.Register(enigma.RegisterOptions{
    Name:            "my-api",
    Upstream:        "https://…",
    PricePerRequest: 0.01,
})

// collect
tx, err := client.Collect(ctx)

sdk

Caller SDK roadmap

For API consumers — calling paid endpoints with automatic payment handling. Planned shape; today, use an x402 client directly (see demo/call.mjs).

javascript

const client = new Enigma({ apiKey: process.env.ENIGMA_API_KEY });

// call a paid API
const res = await client.call('alice/weather', {
  path:   '/v1/now',
  params: { city: 'NYC' },
});

// pre-authorize a session spend limit (agent-friendly)
await client.authorize({ maxSpend: 5.00, expiresIn: '1h' });

// check usage
const usage = await client.usage({ since: '24h' });
// → { calls: 842, spent: { usdc: 4.21 } }

python

client = Enigma(api_key=os.environ["ENIGMA_API_KEY"])

# call a paid API
res = await client.call("alice/weather", path="/v1/now", params={"city": "NYC"})
print(res.data)  # → {'temp': 72, 'unit': 'F'}

# authorize a spend cap
await client.authorize(max_spend=5.00, expires_in="1h")

# usage stats
usage = await client.usage(since="24h")

rust

let client = Enigma::with_api_key(&api_key);

let res = client.call("alice/weather", CallOptions {
    path:   "/v1/now".into(),
    params: hashmap!{ "city" => "NYC" },
    ..Default::default()
}).await?;

let usage = client.usage(UsageOptions { since: Since::Hours(24) }).await?;

go

client := enigma.WithAPIKey(os.Getenv("ENIGMA_API_KEY"))

res, err := client.Call(ctx, "alice/weather", enigma.CallOptions{
    Path:   "/v1/now",
    Params: map[string]string{"city": "NYC"},
})

usage, err := client.Usage(ctx, enigma.UsageOptions{Since: "24h"})

sdk

Configuration roadmap

All SDK clients will share a common configuration interface. Preview only — these options are part of the v0.2 SDK design.

option	type	description
`privateKey`	string	Solana private key (base58). Required for provider operations. Never expose in client-side code.
`apiKey`	string	Enigma API key (`enig_live_…` or `enig_test_…`). Required for caller operations.
`network`	`'devnet' \| 'mainnet'`	Defaults to `'devnet'`. Switch to `'mainnet'` at launch.
`timeout`	number (ms)	Request timeout applied to each proxied call. Default: `30000`.
`retries`	number	Retry count on upstream 5xx errors. Payment is refunded on retry. Default: `1`.
`rpcUrl`	string	Custom Solana RPC endpoint. Defaults to Enigma's managed RPC.

api reference

Authentication

Enigma has two distinct authentication models — one for callers (paying for proxy requests) and one for providers (managing their APIs).

Caller auth — x402 payment protocol

Proxied requests are gated by the x402 payment protocol, not API keys. The flow:

1. The first request returns 402 Payment Required with a JSON price tag (network, recipient PDA, amount in USDC).
2. Your client signs a payment payload with your Solana keypair and re-sends the request with a PAYMENT header.
3. The Enigma proxy validates the payment, settles it on Solana (sub-second devnet finality), then forwards your request upstream. The settlement signature is returned in the PAYMENT-RESPONSE header.

In practice, you don't implement this by hand — use @x402/fetch with the SVM scheme, point it at a signer, and call the proxy URL like a normal fetch. See demo/call.mjs for a working 50-line example.

Provider auth — wallet signature or email OTP

Provider operations (registering APIs, updating prices, collecting revenue) authenticate via the dashboard:

method	how it works
Solana wallet	Phantom or Solflare — connect, sign the transaction, your wallet pubkey is your provider identity.
Email OTP	Sign in with email; the backend issues a Solana account custodied during v0.1. Convert to a self-custodial wallet anytime.

Future API-key auth roadmap

A first-party API key system (for headless dashboards, CI, scripts that prefer key-based auth over wallet signatures) is on the roadmap. The planned prefix scheme:

prefix	environment	funds
`enig_live_`	Mainnet	Real USDC
`enig_test_`	Devnet	Test tokens — no real value

api reference

Endpoints

Base URL: your Enigma deployment host (devnet: enigma-production-efad.up.railway.app). The routes below are the surface area today — flat, no /v1 prefix.

Proxy (x402-priced)

ANY

/{user_name}/{api_name}/*path

Forwards to the API's upstream URL. The request must satisfy the x402 price tag; the proxy settles payment on Solana before forwarding. All HTTP methods pass through verbatim.

POST

/{user_name}/{api_name}

Same as above for POST to the root of the API (no sub-path).

Discovery

GET

/browse

List all public APIs in the marketplace.

GET

/{user_name}

Public user profile.

GET

/{user_name}/apis

List APIs owned by a user.

GET

/{user_name}/{api_name}

API metadata (name, description, upstream — sanitized — price, category).

GET

/user/pubkey/{pubkey}

Look up a user by their Solana public key.

Provider management

POST

/create_user

Create a user record. Body includes user_name and the Solana public key tied to the account.

POST

/{user_name}/create_api

Register a new API. Body: { name, upstream, price_per_request, description?, category? }

DELETE

/{user_name}/{api_name}

Delete an API.

Note — price updates and PDA balance collection happen on-chain today (via the update_global_config / collect_balance instructions). There is no separate HTTP endpoint for them; the dashboard wraps the on-chain calls. Headless wrappers are part of the SDK roadmap.

Email OTP

POST

/send_otp

Send a one-time code to an email address. Body: { email }

POST

/verify_otp

Verify the code. Body: { email, otp }

Planned roadmap

GET

/v1/usage

Usage and spend stats for a caller — planned alongside the SDK.

POST

/v1/authorize

Session-level spend authorization for agents.

security

Trust Model

Enigma is built on one principle: the platform should never be able to steal from its users.

How funds flow

When a caller pays for a request, USDC moves from their account directly into a program-derived token account (PDA) seeded by the developer's public key. At no point does USDC pass through Enigma's own wallet.

entity	can drain developer PDA?
Enigma platform	no — no admin key exists
Other developers	no — PDA seeded by your key only
API callers	no — can only pay in, never withdraw
You (the developer)	yes — only you can invoke collect_balance

If Enigma goes offline: Your PDA and its USDC balance remain on-chain. You can invoke collect_balance directly via any Solana RPC — no Enigma infrastructure needed. The program is immutable once deployed.

security

Non-Custodial Design

Every dollar you earn sits in a program-derived account (PDA) derived from your wallet address. The math that generates this address ensures only you can authorize a withdrawal.

PDA seed derivation

rust (on-chain)

// programs/enigma/src/instructions/collect_balance.rs
#[account(
    seeds = [b"USER_DATA_SEEDS",
             global_config.key().as_ref(),
             developer.key().as_ref()], // your wallet pubkey
    bump   = user_data.bump,
    constraint = user_data.dev == developer.key()
)]
pub user_data: Account<UserData>,

// Only a signer derivable from these exact seeds can
// sign the transfer_checked CPI out of this account.
transfer_checked(
    CpiContext::new_with_signer( token_program,
        TransferChecked { from: user_data_ata, to: dev_ata,
                          authority: user_data.to_account_info() },
        signer_seeds),
    net, mint.decimals)?;

Verify your PDA on-chain

Inspect your PDA and its USDC balance at any time using any Solana RPC or explorer:

shell

$ solana account YOUR_PDA_ADDRESS --url devnet
$ spl-token balance --address YOUR_PDA_ATA --url devnet

The program ID is 9H7DLg3YkfVQgdVZxhiwdd5GtoAWrJvrQURtZKY7N5tu (devnet). Source code is publicly auditable on GitHub.

faq

FAQ

Do I need to change my API code to use Enigma? +

No. Enigma is a proxy layer. Your upstream API receives requests exactly as before — it never knows Enigma is in the middle. No new dependencies, no middleware, no code changes.

What happens if my upstream API goes down? +

If the proxy receives a 5xx response from your upstream, the caller is automatically refunded. The USDC transfer is reverted before it settles. Enigma does not charge for failed requests.

Can I offer a free tier alongside a paid tier? +

Yes. Set pricePerRequest: 0 for free-but-metered access. Register a separate API name for the paid version, or use the upcoming tiered pricing feature (Q3 roadmap) for rate-limited free + paid overages on one endpoint.

How fast do I receive payment? +

Payment settles inside the request cycle on Solana — typically ~400ms. Your PDA balance updates before the caller receives the response. Collect to your wallet anytime after that, instantly.

Can AI agents call Enigma-proxied APIs? +

Yes — this is one of our primary use cases. Today, agents sign each x402 payment directly from a Solana keypair (no wallet pop-up, no human in the loop — see demo/call.mjs). A session-level spend-cap helper (client.authorize()) is on the roadmap so agents can declare an upper bound once and avoid per-call signing.

Is the platform fee negotiable? +

The current platform fee is 10% (1000 bps), set in the on-chain global config. For high-volume design partners, we're open to custom rates — reach out on Discord or directly after the pitch.

What blockchains are supported? +

Solana only, currently. Settlement is in USDC (SPL token). An Ethereum / x402 protocol bridge is on the 90-day roadmap for cross-chain access.

Is Enigma open source? +

Yes. The Anchor program, the Rust proxy server, and the Next.js dashboard all live in the same monorepo and are verifiably deployed on-chain (program ID below). The SDK will join the same repo when it's ready.

What happens to my funds if Enigma shuts down? +

Nothing bad. Your PDA and its USDC balance live on-chain permanently. You can call collect_balance directly via any Solana RPC — no Enigma servers required. The program is immutable once deployed, and your funds are always recoverable.