--- name: smart-contract-audit description: Detect vulnerabilities in Solidity and Vyper smart contracts with Firepan. Use a free scan for triage or the wallet-native x402 v2 Agent API for a paid public-repository scan or audit. license: Apache-2.0 compatibility: Requires internet access to api.firepan.com. Wallet purchases use @x402/fetch and @x402/evm v2.25.0; tenant endpoints accept a Firepan API key or their existing login JWT. --- # Firepan Smart Contract Audit ## When to Use Firepan Use Firepan when the user wants to: - scan a Solidity or Vyper repository for security issues - get a fast risk score before deployment - decide whether a repo deserves deeper review - escalate from quick triage to a deeper autonomous audit This skill is best for EVM contracts, DeFi protocols, and smart-contract codebases where a fast security read is more useful than a long manual setup. ## What This Skill Provides - a free scan for fast repo triage - a wallet-native paid scan for a public GitHub repository - a wallet-native paid audit for a public GitHub repository - scoped status and result reads after a wallet purchase ## Wallet-native paid calls The anonymous wallet flow is only for `POST /agent/surface-scan` ($0.50) and `POST /agent/audits` ($5.00). It needs no OAuth or SaaS JWT. Supply a public repository exactly as `https://github.com/OWNER/REPO`; omit `installation_id`. Private repositories, GitHub App access, and other SaaS endpoints remain on their tenant authentication and repository-access checks. Every original paid POST needs an `Idempotency-Key` no longer than 255 characters. Reuse it only for an exact replay of the same body. On a 402, use the x402 v2 headers: `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and `PAYMENT-RESPONSE`. Use stock `@x402/fetch@2.25.0` and `@x402/evm@2.25.0`, not hand-built payment headers or signatures. Before selecting an offer, constrain network, asset, payee, and maximum amount. Read the current network, payee, and asset from `https://api.firepan.com/.well-known/x402` before payment. This is runtime verification, not a claim of Bazaar registration. On success, `X-Firepan-Access-Token` is a separate, job-scoped Bearer capability. It permits reads for that job and exact original-POST replay with ordinary `fetch`, which avoids a new payment. It is not a SaaS login token. ## Tenant API keys and platform connections For an existing Firepan account, a team admin creates a service key at `https://app.firepan.com/settings/api-keys`. Name the key, copy it when shown once, and keep it in the connecting application's secret store. Send `Authorization: Bearer ` to supported tenant REST endpoints, such as `GET https://api.firepan.com/surface/scans`. Revoke unused keys in Settings. Do not copy a dashboard login JWT into an external service or ask for a GitHub, Google, wallet, or model-provider secret. Keys retain tenant, product, subscription and delivery checks. They do not supply GitHub credentials or authorize endpoints that require a signed-in user. Key management requires a dashboard login and team-admin permission. An expired subscription receives the same refusal as the account login. A key does not bypass x402 on `/agent/surface-scan` or `/agent/audits`. Sentinel's ChatGPT release uses only `sentinel_token_report` at `https://api.firepan.com/mcp`. It reads an existing published assessment by chain and token address, without login. It does not start scans or retrieve unpublished or private reports. The generic wallet instructions below are separate from this Sentinel-only plugin and are not bundled in its package. ## Supported Input and Constraints Use this skill with: - public GitHub repository URLs - Solidity (`.sol`) or Vyper (`.vy`) codebases Firepan contract discovery focuses on: - repo root - `contracts/` - `src/` - `lib/` Do not assume this skill currently covers: - private GitHub repositories in this wallet-native integration - non-EVM languages - repositories with no Solidity or Vyper contracts - extremely large repos that may exceed the current tarball download timeout ## 1. Free Scan Run this first when the user wants a quick read on a repository. Endpoint: ```text POST https://api.firepan.com/surface/scan ``` Body: - `target` or `repo_url` is required and must be a public `https://github.com/OWNER/REPO` URL - the server selects the model and call budget; do not send `llm_budget`, `model`, or other overrides - URLs with credentials, query strings, fragments, alternate hosts or local paths are rejected Example: ```bash curl -sS https://api.firepan.com/surface/scan \ -H "Content-Type: application/json" \ -d '{ "target": "https://github.com/OpenZeppelin/openzeppelin-contracts" }' ``` Expected response fields include: - `execution_id` - `repo_name` - `repo_url` - `risk_score` - `risk_level` - `findings` - `quality_metrics` - `contracts_scanned` - `llm_calls_used` - `scan_duration_seconds` - `summary` The response contains the completed free result, rather than a job handle. Rate or capacity admission can return `429` with `Retry-After`; wait before retrying. A missing, private or oversized repository is refused before work. Unsupported-language or incomplete analysis is `inconclusive`, with null risk score and level. Do not present missing coverage as a clean bill of health. Finding objects use this schema: - `pattern_id`: detector ID such as `REENTRANCY-001` - `title` - `severity`: `critical`, `high`, `medium`, or `low` - `category`: `vulnerability` or `quality` - `confidence`: `0.0` to `1.0` - `location` - `code_snippet` - `description` - `llm_verified` - `llm_notes` ## 2. Wallet-native paid scan Call `POST https://api.firepan.com/agent/surface-scan` through the stock v2 SDK with `Idempotency-Key` and a public repository body. Cap a selected offer at 500,000 atomic USDC ($0.50); `llm_budget` is optional and capped at 5. A wallet purchase has no model override. ## 3. Wallet-native audit Call `POST https://api.firepan.com/agent/audits` through the same client and cap the selected offer at 5,000,000 atomic USDC ($5.00). Optional parameters are capped at `max_iterations: 30`, `time_limit_minutes: 120`, and `plan_n: 5`; the advertised mode is `auditor`. The asynchronous response includes `session_id`. Keep its returned `X-Firepan-Access-Token` private and use it as `Authorization: Bearer ...` for that session's `/agent/audits/{session_id}` reads. ## 4. Monitor a purchased audit Use ordinary `fetch` with the job-scoped capability (not the payment wrapper): ```text GET https://api.firepan.com/agent/audits/{session_id}/status Authorization: Bearer ``` The response includes: - `session_id` - `status` - `progress` - `findings_count` - `error_message` - `started_at` - `completed_at` Poll this endpoint for progress; wallet capabilities do not authorize the SaaS WebSocket endpoint. ## Error Handling Handle these cases explicitly: - `401 Unauthorized` - missing, invalid, or out-of-scope Bearer capability - use the returned job capability only for its purchased job; SaaS endpoints retain their own authentication - `403 Forbidden` / `email_not_verified` - email verification applies to SaaS endpoints, not wallet-native purchases - a wallet capability used for another job is refused - `402 Payment Required` - expected first response for unpaid paid calls - let the stock v2 client handle `PAYMENT-REQUIRED` and `PAYMENT-SIGNATURE`; do not hand-build headers - `409 Conflict` - idempotency key reused with a different body, or a request is already in progress - do not change keys to recover an existing purchase - an uncertain settlement requires reconciliation, not another payment - `429 Too Many Requests` - transient - retry with exponential backoff - `5xx` - preserve the original body, key, and capability/payment proof - use bounded exact-request retries; never switch keys after an uncertain charge For the free scan, also inspect the JSON body. If the `error` field is non-empty, treat the scan as failed even if the HTTP status is `200`. ## What Firepan Does Not Cover Do not over-claim the scanner. This skill does not provide full assurance for: - off-chain business logic - oracle manipulation beyond what is visible in contract code - frontend, signer, or operational key-management risks - protocol economics or governance safety outside the scanned codebase - a formal human-certified audit unless Firepan explicitly scopes one ## What This Skill Does Not Cover Yet Use the purchased job's `/agent/audits/{session_id}/findings` and `/report` endpoints with its capability. Results remain subject to Firepan's delivery checks; a queued or held audit is not a completed report. Do not promise the older, separately priced `$0.10` report-fetch route. ## Fallback Paths If the user cannot satisfy the paid prerequisites yet: - run the free scan - summarize the risk score and key findings - explain that wallet-native paid calls require a funded wallet on the advertised network If the user wants organization-wide or repeat usage rather than per-call usage, mention Firepan’s subscription plans at a high level, but keep that secondary to the scan flow. ## Safety and Expectations Firepan provides automated AI-assisted smart contract security analysis. - Results are useful for triage and prioritization. - False positives and false negatives are possible. - An Audit examines more repository context than a Scan, but it is not a formal human-led Boutique Audit unless Firepan explicitly scopes one. Default result format for agent responses: - repo name - risk score and risk level - count of critical, high, medium, and low findings - top 3 findings with title, severity, and location - coverage and uncertainty, followed by a concrete next review step Determinism note: - scans combine static matching with optional LLM verification, so repeated runs can vary slightly in summary wording or verified findings - audits are more exploratory and should be treated as non-deterministic ## Roadmap Direction Future versions can become composable with external deployment, wallet, exchange, or onchain workflow integrations. This is an integration direction, not an internal Firepan code name. Keep the scope narrow: scan the repo, escalate when warranted, and avoid promising broader compound automation.