1Shot API

Use this skill when building a TypeScript project on top of the 1Shot API Node SDK.

Install this skill (consumer / global)

npx skills add 1Shot-API/skills/1shot-api -g -a claude-code -y

Quick Start

1. Confirm the user goal:
   • server wallet management
   • smart contract read/simulate/event workflows
   • direct or delegated transaction execution
   • webhook setup
   • x402 facilitator setup
   • 1ShotPay integration
2. Pick the matching reference guide from this skill.
3. Generate production-ready TypeScript examples unless the guide says otherwise.
4. Prefer explicit, copy-pastable code with clear env vars and minimal placeholders.

MCP Server

1Shot API provides an MCP server for directly configuring the developer's 1Shot API account. Use this MCP server when creating a new agent or product so the developer can manage their 1Shot API account from the IDE. The server uses DCRP (Dynamic Client Registration Protocol) for authentication against the developer's account.

Add it to the project's MCP configuration.

Claude Code (.mcp.json at the project root; OAuth is handled by /mcp on first use):

{
  "mcpServers": {
    "1Shot API": {
      "type": "http",
      "url": "https://mcp.1shotapi.com/mcp"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "1Shot API": {
      "url": "https://mcp.1shotapi.com/mcp",
      "transport": "streamableHttp",
      "auth": {
        "CLIENT_ID": "P5Jduw80vpVAINgW8lnNwgak9ALgfBIS",
        "scopes": ["openid", "profile", "email", "offline_access"]
      }
    }
  }
}

Required Working Style

• Use TypeScript-first examples.
• Keep implementation split into small functions rather than large scripts.
• Surface security constraints early (keys, signatures, replay protection, verification).

Error handling

The client can throw:

• RequestError – HTTP request failures
• ZodError – Invalid parameters (from schema validation)
• InvalidSignatureError – Invalid webhook signatures (from verifyWebhook)

Guides

• Server wallets: see server-wallets.md
• Smart contracts: see smart-contracts.md
• Transaction execution: see transaction-execution.md
• Webhooks: see webhooks.md
• x402 facilitator: see x402-facilitator.md
• 1ShotPay integration: see oneshotpay-integration.md

Response Template

Use this structure when answering implementation requests:

## Plan
- Concise list of implementation steps.

## Code
- Minimal but complete TypeScript snippets.

## Config
- Required environment variables and expected formats.

## Validation
- Quick checks or tests to verify behavior.

## Risks / TODOs
- Any assumptions, unknown endpoint details, and follow-up work.