JavaScript / TypeScript SDK

The official TypeScript SDK provides full API parity with the 1Claw REST API. It supports both human and agent workflows, x402 auto-payment, and an MCP tool layer for AI agents.

Repository: github.com/1clawAI/1claw-sdk

API contract: The SDK is built against the OpenAPI 3.1 spec. Request/response types are generated from it. The spec is published as @1claw/openapi-spec (npm) for codegen or custom clients. See API reference for the endpoint list.

Try it out

Try out the examples in this repo: Basic (vault, secrets, billing, sharing) and Next.js Agent Secret (chat app with server-side vault access).

Install

npm install @1claw/sdk

Quick start

import { createClient } from "@1claw/sdk";

const client = createClient({
    baseUrl: "https://api.1claw.xyz",
    apiKey: process.env.ONECLAW_API_KEY, // personal API key (1ck_...)
});

// Create a vault
const { data: vault } = await client.vault.create({
    name: "my-vault",
    description: "Production secrets",
});

// Store a secret
await client.secrets.set(vault.id, "STRIPE_KEY", "sk_live_...", {
    type: "api_key",
});

// Retrieve a secret
const { data: secret } = await client.secrets.get(vault.id, "STRIPE_KEY");
console.log(secret.value); // use securely, don't log in production

Authentication

The SDK supports three authentication methods:

// 1. Personal API key (recommended for server-side)
const client = createClient({
    baseUrl: "https://api.1claw.xyz",
    apiKey: "1ck_...",
});

// 2. Agent credentials
const client = createClient({
    baseUrl: "https://api.1claw.xyz",
    agentId: "uuid",
    apiKey: "ocv_...",
});

// 3. Manual auth (signup, email/password)
const client = createClient({ baseUrl: "https://api.1claw.xyz" });
await client.auth.signup({
    email: "me@example.com",
    password: "...",
    display_name: "Me",
});
// or
await client.auth.login({ email: "me@example.com", password: "..." });

Resource modules

All API endpoints are organized into resource modules:

Module	Methods
`client.auth`	`login()`, `signup()`, `agentToken()`, `apiKeyToken()`, `google()`, `changePassword()`, `logout()`, `forgotPassword()`, `resetPassword()`, `sendEmailOtp()`, `verifyEmailOtp()`, `socialLogin()`, `exchangeOAuthCode()`, `exchangeFederatedToken()`
`client.vault`	`create()`, `list()`, `get()`, `delete()`
`client.secrets`	`set()`, `get()`, `list()`, `delete()`, `rotate()`, `listVersions()`, `getVersion()`, `rotateGenerate()`, `disableVersion()`
`client.access`	`grantHuman()`, `grantAgent()`, `update()`, `revoke()`, `listGrants()`
`client.agents`	`create()`, `list()`, `get()`, `update()`, `delete()`, `rotateKey()`, `enroll()`, `submitTransaction()`, `signTransaction()`, `listTransactions()`, `getTransaction()`, `simulateTransaction()`, `simulateBundle()`, `signIntent()`, `leaseBankrKey()`, `listBankrKeys()`, `revokeBankrKey()`
`client.signingKeys`	`create()`, `list()`, `rotate()`, `deactivate()`, `export()`
`client.sharing`	`create()`, `access()`, `revoke()`
`client.approvals`	`request()`, `list()`, `get()`, `decide()`
`client.apiKeys`	`create()`, `list()`, `revoke()`
`client.billing`	`usage()`, `history()`, `subscribe()`, `portal()`, `subscription()`, `creditsTopup()`, `creditsBalance()`, `creditsTransactions()`, `llmTokenBilling()`, `subscribeLlmTokenBilling()`, `disableLlmTokenBilling()`
`client.audit`	`query()`
`client.org`	`listMembers()`, `updateMemberRole()`, `removeMember()`, `getBankrConfig()`, `setBankrConfig()`, `deleteBankrConfig()`
`client.x402`	`getPaymentRequirement()`, `pay()`, `verifyReceipt()`, `withPayment()`
`client.chains`	`list()`, `get()`
`client.treasury`	`create()`, `list()`, `get()`, `update()`, `delete()`, `addSigner()`, `removeSigner()`, `propose()`, `listProposals()`, `getProposal()`, `signProposal()`, `executeProposal()`
`client.treasuryWallets`	`generate()`, `list()`, `get()`, `balance()`, `send()`, `swap()`, `export()`, `rotate()`, `deactivate()`, `getEffectiveSpendPolicy()`
`client.platform`	`createApp()`, `listApps()`, `getApp()`, `updateApp()`, `deleteApp()`, `createTemplate()`, `listTemplates()`, `upsertUser()`, `bootstrapUser()`, `reissueClaim()`, `listConnectedApps()`, `claimPreview()`, `claimRedeem()`, `createSpendPolicy()`, `listSpendPolicies()`, `setUserSpendPolicy()`, `deleteSpendPolicy()`
`client.devices`	`list()`, `revoke()`
`client.passkeys`	`list()`, `register()`, `delete()`
`client.depositDestinations`	`create()`, `list()`, `get()`, `update()`
`client.internalAccounts`	`create()`, `list()`, `get()`, `transfer()`, `getLedger()`
`client.fiat`	`createOnrampSession()`, `initiateOfframp()`
`client.risk`	`listEvents()`, `getVerdict()`, `listVerdicts()`, `createHoneytoken()`, `listHoneytokens()`, `deleteHoneytoken()`

Share a secret with someone who may not have an account yet:

const { data: share } = await client.sharing.create(secretId, {
    recipient_type: "external_email",
    email: "colleague@example.com",
    expires_at: "2026-04-01T00:00:00Z",
    max_access_count: 3,
});
// Recipient gets an email; the share auto-claims when they sign up/log in

Response envelope

Every method returns { data, error, meta }:

const res = await client.secrets.get(vaultId, "MY_KEY");
if (res.error) {
    console.error(res.error.message); // typed error
} else {
    console.log(res.data.value);
}

Error types

import {
    OneclawError,
    AuthError, // 401
    PaymentRequiredError, // 402 (x402)
    ApprovalRequiredError, // 403 (approval pending)
    NotFoundError, // 404
    RateLimitError, // 429
} from "@1claw/sdk";

MCP tool integration

The SDK includes an MCP tool layer for AI agent frameworks:

import { McpHandler, getMcpToolDefinitions } from "@1claw/sdk/mcp";

// Get tool schemas for registration with an AI framework
const tools = getMcpToolDefinitions();

// Handle tool calls
const handler = new McpHandler(client);
const result = await handler.handle("1claw_get_secret", {
    vault_id: "...",
    key: "STRIPE_KEY",
});

Available MCP tools: 1claw_get_secret, 1claw_set_secret, 1claw_list_secret_keys, 1claw_request_approval, 1claw_check_approval_status, 1claw_pay_and_fetch, 1claw_create_vault, 1claw_list_vaults, 1claw_share_secret.

Examples

See the examples repository (27 runnable demos). Highlights:

Example	What it demonstrates
basic	Vault CRUD, secrets, billing, sharing, Intents API
langchain-agent	LangChain agent fetches secrets just-in-time
nextjs-agent-secret	Next.js chat app with server-side vault access
fastmcp-tool-server	Custom MCP server with domain tools
shroud-demo	Shroud TEE proxy: health, Intents API, LLM routing
shroud-llm	LLM Token Billing via Stripe AI Gateway
tx-simulation	On-chain signing with guardrails + Tenderly simulation
multi-chain-keys	HSM signing keys for 6 blockchains
evm-signing	EIP-191, EIP-712, and EIP-2718 transaction types
agentic-tx	End-to-end fund → sign → broadcast with guardrails
platform-connect	Platform API bootstrap templates + user provisioning
treasury-wallets	Multi-chain treasury wallets, balances, send
x402-payments	Real x402 micropayments against 1Claw endpoints
ampersend-x402	Ampersend smart-account x402 + MCP/HTTP clients
anthropic-wif	OIDC federation → Anthropic Workload Identity
python-sdk	Python client: vault, secrets, billing, agent auth

Full catalog and run instructions: examples README. From the monorepo: ./examples/scripts/test-all-examples.sh.

OpenAPI types

The SDK’s TypeScript types are generated from the OpenAPI 3.1 spec. You can import raw generated types:

import type { paths, components, operations, ApiSchemas } from "@1claw/sdk";

type Vault = ApiSchemas["VaultResponse"];
type Agent = ApiSchemas["AgentResponse"];

To regenerate types after spec changes (when working from the monorepo): npm run generate in the SDK package.

Human API (dashboard / server)

The dashboard uses fetch and TanStack Query with the same base URL and JWT. There is no separate "human" SDK package; use @1claw/sdk or fetch with the Human API docs.

Install​

Quick start​

Authentication​

Resource modules​

Sharing by email​

Response envelope​

Error types​

MCP tool integration​

Examples​

OpenAPI types​

Human API (dashboard / server)​