TxShield API

Stop wasting SOL on dead transactions. Drop an unsigned tx in, get back the fee bucket your bot needs to land, the slippage the route will actually take, the simulation outcome, and a per-vector risk breakdown — typically in under 80 ms.

Overview

Every Solana transaction faces the same three execution risks before it lands: it gets dropped or stuck because the priority fee is in the wrong bucket, the route slips harder than the wallet UI estimated, or it reverts at execution for a reason the wallet never surfaced. TxShield runs all three checks pre-flight in a single /simulate call so wallets and bots can either bump the fee, switch the route, abort the tx, or proceed with confidence.

The same call also runs the safety checks — program blacklist, sandwich-attacker proximity, rug-pull / honeypot, durable-nonce, flash-loan / oracle. MEV / sandwich detection is currently production beta and treated as advisory; the execution-quality vectors (landing, slippage, simulation, fees) are GA.

Base URL: https://api.txshield.dev. All endpoints under /api/v1/. JSON in, JSON out. UTF-8. ISO 8601 timestamps in UTC.

01Quickstart

Five minutes from npm install to your first verdict.

1. Get an API key

Sign in to the dashboard and create a key under Settings → API keys. Each key is scoped to one project, lives in one of three modes (test, live, internal) and can be rotated or revoked at any time.

2. Pick how you call us

The API is plain HTTP — every endpoint is a one-line curl. Official TypeScript and Python SDKs are shipping under Beta Milestone 1 of the Solana Foundation Developer Tooling grant; until they land on npm / PyPI, use curl or generate a client from the OpenAPI 3.1 spec with the generator of your choice.

# nothing to install — just curl + your keyexport TXSHIELD_KEY="txshield_live_..."

# ships under Beta Milestone 1 — track at /changelognpm install @txshield/sdk     # not yet published

# ships under Beta Milestone 1 — track at /changelogpip install txshield        # not yet published

3. First request

curl -X POST "https://api.txshield.dev/api/v1/solana/tx/simulate" \  -H "X-API-Key: $TXSHIELD_KEY" \  -H "Content-Type: application/json" \  -d '{"transaction": "<base64-versioned-tx>", "policy": "wallet-default"}'

// SDK shape — ships under Beta Milestone 1 (Solana Foundation grant).import { TxShield } from "@txshield/sdk";const tx = new TxShield({ key: process.env.TXSHIELD_KEY! });const v = await tx.solana.simulate({  transaction: unsignedB64,         // VersionedTransaction.serialize() → base64});if (v.risk.risk_level === "critical") {  throw new Error(`refused: ${v.failure_reason}`);}

# SDK shape — ships under Beta Milestone 1 (Solana Foundation grant).from txshield import TxShieldtx = TxShield(key=os.environ["TXSHIELD_KEY"])v = tx.solana.simulate(transaction=unsigned_b64)if v.risk.risk_level == "critical":    raise RuntimeError(f"refused: {v.failure_reason}")

4. Read the verdict

The response envelope is the same shape on every chain.

{
  "success": true,
  "compute_units": 28104,
  "suggested_compute_limit": 31000,
  "fee_estimate_sol": 0.0000125,
  "priority_fees": {
    "low": 1000, "medium": 10000,
    "high": 100000, "very_high": 1000000,
    "samples": 312
  },
  "slippage": { "bps": 7, "route": "jupiter-v6" },
  "risk": {
    "mev_score": 0.04, "mev_level": "none", "mev_type": null,
    "has_blacklisted_program": false,
    "blacklisted_programs": [],
    "dex_programs": ["JUP6L…AG4"],
    "token_risk": null,
    "flash_loan_risk": { "detected": false, "oracle_manipulation": false },
    "durable_nonce": { "detected": false, "address": null },
    "risk_level": "low"
  },
  "landing_estimate": {
    "fee_percentile_bucket": "low",
    "submitted_fee_microlamports": 1000,
    "recommended_fee_for_high_landing": 12500
  },
  "recommendations": [],
  "program_breakdown": […],
  "call_tree": […]
}

02Authentication

Two layers, picked by call site:

• API keys (X-API-Key: txshield_live_…) — for server-to-server traffic. Created via the dashboard or POST /api/v1/api-keys. Three modes: test, live, internal.
• JWT bearer tokens (Authorization: Bearer eyJ…) — for the dashboard SPA itself and any human-driven flow. 24h expiry on access, 30d on refresh. Four ways to obtain one (see below).

Both authenticate the same endpoints. Where you use which is a security choice — never put an API key in client-side code.

Four sign-in methods (all issue a JWT bearer)

Wallet sign-in — the wire shape

Two calls. First fetch a nonce; second submit the signature.

# 1. Get a challenge for this pubkeycurl -X POST "https://api.txshield.dev/auth/wallet/challenge" \  -H "Content-Type: application/json" \  -d '{"pubkey": "<base58-wallet-address>"}'# → { "nonce": "...", "message": "txshield.dev wants you to sign in...\nNonce: ...\nIssued: ..." }# 2. Sign the `message` with the wallet, then submitcurl -X POST "https://api.txshield.dev/auth/wallet/login" \  -H "Content-Type: application/json" \  -d '{"pubkey": "...", "signature": "<base58-ed25519-sig>", "nonce": "..."}'# → { "token": "eyJ...", "refresh_token": "eyJ...", "user": { ... } }

Nonces expire after 5 minutes and are single-use. The signed message follows the SIWS draft so wallet UIs render it as a human-readable prompt, not opaque bytes.

Scoped session tokens (browser-safe)

For wallet/mobile origins that already have a JWT, mint a short-lived session token server-side and hand it to the client. Tokens expire after 15 minutes and are bound to a single user wallet so leakage has a tiny blast radius.

03Solana — single simulation

The core of the product. Submit one unsigned VersionedTransaction serialized as base64. We simulate it against mainnet state, run the 14 detection vectors in parallel, and return a single envelope.

Request body

Response — top-level fields

Solana — batch simulation

Up to 50 transactions in one round-trip. Use it when your bot evaluates multiple candidate routes per block — saves the round-trip latency on N-1 of them.

Solana — streaming verdicts

WebSocket connection for sub-50 ms verdicts. Send a JSON envelope per line; receive verdicts as they finish. Authenticate with the ?api_key=… query param at connect time. Connection idle-timeout 60s — send a ping if you've gone quiet.

Simulation history

Paginated list of past simulations on this account. Query params: limit (default 25, max 200), cursor (opaque string from previous page), since/until (ISO 8601), risk_level, has_blacklisted_program.

Retention: 90 days by default; up to 7 years for volume customers (negotiated per tenant).

Aggregate stats

Pre-computed aggregates for the dashboard widget: total sims, 24h count, success rate, P50/P95/P99 latency. Refreshed every 60s.

04Detection · MEV / sandwich

Detects front-run + back-run pairs against monitored Solana DEX programs (Jupiter, Raydium, Orca, Meteora, Lifinity). Returns:

• risk.mev_score — float 0.00–1.00. Aggregate likelihood the tx will be sandwiched at submit-time.
• risk.mev_level — bucketed: none, low, medium, high, critical.
• risk.mev_type — concrete pattern when high: "sandwich", "jit", "backrun_only".

Treat high/critical as a hard refusal in production. medium usually means you should re-route through a private mempool or wait for the next block.

Detection · Rug-pull / honeypot

Engaged when the tx touches an SPL-token program. Checks:

• Mint authority + freeze authority status (active = high risk).
• LP-lock duration; lock unlocks < 7 days fire medium.
• Top-10 holder concentration. > 80% fires high.
• Sell-test simulation — would a sell tx revert? If yes → critical honeypot.

Detection · Slippage overflow

Pulls live route quotes from Jupiter Price API at submit-time priority fees — not the stale UI estimate. Returns slippage.bps as worst-case basis points and slippage.route as the chosen route. Use recommendations to surface alternative routes when bps > your threshold.

Detection · Program safety

Curated and customer-submitted blacklist of malicious programs anywhere in the CPI tree. Categories:

Per-tenant overrides for volume customers — extend the list with your own blocklist/allowlist.

Detection · Priority fee

Live getRecentPrioritizationFees sampling per program. Returned as p25/p50/p75/p95 inside priority_fees. Use the medium percentile as the default tip; jump to high when landing latency matters more than fee cost.

Detection · Pre-flight simulation

The basis for everything else. Solana simulateTransaction with full pre-execution against mainnet state. Returns balance changes, CPI call tree, per-program compute units, and revert reasons in compute_units, program_breakdown, call_tree, failure_reason.

05Webhooks

Register a URL to receive verdict events in real-time. We POST a JSON payload to your URL whenever an event of a type you subscribed to fires. Default delivery latency: < 200 ms after the originating event.

Subscribable event types

Signature verification

Every webhook delivery carries an X-TxShield-Signature header — HMAC-SHA256 over the raw body, signed with your endpoint's secret. Verify in your handler before trusting the payload:

import { createHmac, timingSafeEqual } from "node:crypto";function verify(rawBody: Buffer, signature: string, secret: string) {  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));}

Retry policy

If your endpoint returns a non-2xx status (or doesn't respond within 8s), we retry with exponential backoff: 30s, 2m, 10m, 1h, 6h. After the 5th attempt we mark the delivery as failed; you can manually replay it from the dashboard. Idempotency: each delivery carries a stable delivery_id in the body — use it to dedupe on your side.

06API keys

Manage keys programmatically or via the dashboard. The cleartext key is only returned once — at creation. After that you only see the prefix (e.g. txshield_live_) and metadata (requests_count, last_used_at, created_at).

Rotation is graceful: the new key activates immediately, the old one stays valid for 24h, then auto-revokes. No downtime.

07Billing

Pure pay-as-you-go. 1,000 simulations per day on the house, then €0.002 per simulation past that, billed at the end of the calendar month. No tiers, no monthly fee, no commitment, no feature gating — every account gets every detection vector, webhooks, batch and WebSocket from day one. A separate /submit relay tier charges €0.003 per billable submit-strategy call (staked sender, managed-tip Jito); direct and auto-direct submits are free. Jito tips pass through at exact cost.

Above ~5M sims / month? Volume customers get a negotiated per-call rate, a dedicated regional cluster (99.99% SLA), SOC 2 / ISO 27001 evidence pack, and Slack-Connect with 1-hour pager response. Email hello@txshield.dev.

Refunds & disputes

Because this is pay-as-you-go, every line on your monthly invoice corresponds to a specific API call we logged. You can query the underlying records via GET /api/v1/solana/simulations (simulations) or GET /api/v1/solana/submissions (relay submits) to verify any charge against your own logs.

If a charge is wrong — double-billed, metering glitch, service degradation that materially affected your usage — email hello@txshield.dev within 14 days of the invoice date with the invoice number and a brief description. We refund or credit verified billing errors within 5 business days. Stripe disputes through your card issuer also work, but are slower and noisier; we would rather hear from you first.

Cancellation: cancel any time at /billing or via the Stripe Customer Portal. The current billing period is not prorated — you keep API access through end of month, then your account reverts to the 1,000-sim/day free tier (no data loss, no key rotation required).

EU consumer right of withdrawal (§ 312g BGB) applies only to B2C purchases. Business accounts (USt-IdNr provided at signup) are commercial contracts under § 14 BGB and not subject to the 14-day withdrawal window; the refund window above is a voluntary policy we offer regardless.

Endpoints:

checkout creates a Stripe Checkout session for the metered subscription and returns a redirect URL. portal creates a Customer Portal session for managing payment methods, invoices, and cancellation. Adding a card just lifts the throttle — you're never charged for the first 1,000/day.

08Errors

HTTP status codes are load-bearing. Read them.

All error responses share a JSON shape:

{
  "error": {
    "code": "invalid_transaction",
    "message": "failed to deserialize VersionedTransaction: …",
    "request_id": "req_01HVZX9P3J4D2TJYP91D"
  }
}

09Rate limits

Per-API-key rate limits, enforced at the edge. Burst window: 1 second.

Headers on every response:

• X-RateLimit-Limit — your steady-state cap.
• X-RateLimit-Remaining — calls left in the current second.
• X-RateLimit-Reset — Unix epoch when the bucket refills.
• Retry-After — seconds to wait (only on 429).

10SDKs

Until the official SDKs ship under Beta Milestone 1 of the Solana Foundation Developer Tooling grant, curl + a generated client from the OpenAPI spec is the supported path. Every endpoint is doc-equivalent to a one-line curl; see the request examples above.

• TypeScript SDK (@txshield/sdk) — ships under Beta Milestone 1. ESM + CJS, fetch-based, Node 18+ / Bun / Deno / Cloudflare Workers / Vercel Edge. Not yet on npm.
• Python SDK (txshield) — ships under Beta Milestone 1. Sync + async clients, Python 3.10+. Not yet on PyPI.
• txshield-cli — also a Beta Milestone 1 deliverable. Terminal tool for ad-hoc simulate and safety-feed queries without writing code.
• curl — every endpoint is doc-equivalent to a one-line curl. See request examples above.

Other languages: use the OpenAPI spec at /openapi.json with your generator of choice. We test against openapi-typescript, openapi-python-client, and oapi-codegen (Go); pull-requests welcome for additional generators once the grant SDKs land.

11Changelog

• 2026-05-27 — Wallet-first auth shipped: Sign-In-With-Solana via Phantom / Backpack / Solflare / Glow, plus Google + GitHub OAuth. Email + password kept as the fourth option. See Authentication.
• 2026-05-27 — landing_estimate added to /simulate response: tells you which validator-fee percentile bucket your submitted priority fee falls into, with a concrete uplift target if you're in the low bucket.
• 2026-05-25 — Threat-model expansion: flash_loan_risk + durable_nonce response fields, plus matching abort_on_flash_loan_oracle and abort_on_durable_nonce request params. Renamed abort_on_critical_risk → abort_on_active_threat (old name still accepted for one release; deprecation header set).
• 2026-05-24 — tx.finality webhook event: post-submit finality monitor confirms finalized / dropped / reverted without RPC polling.
• 2026-05-06 — Pricing simplified to pure pay-as-you-go: 1,000 sims/day free, €0.01/sim past that. No tiers, no monthly fee. Stripe metered billing live.
• 2026-05-05 — Dashboard SPA migrated to its own niso package; nginx routing fixed via panel-proxy.
• 2026-04-24 — TxShield API adopted into niso package management. No customer impact.
• 2026-04-21 — Helius RPC degradation incident (9 min, partial latency increase). Resolved.
• 2026-04-09 — Webhook delivery backlog (22 min, no drops). Improved retry backoff curve.