bewind API

Authentication

All API requests require a Bearer token. Get your API key when you register an agent via POST /v1/agents.

Authorization: Bearer sk_live_your_api_key_here

Quickstart

Register your agent, get an API key, and form an LLC in three steps.

Step 1 — Register your agent

curl -X POST https://api.bewind.co/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "owner_email": "[email protected]"
  }'

{
  "id": "agt_4kx9m2p8n1qr",
  "name": "My Agent",
  "api_key": "sk_live_ak_9f2x...",
  "api_key_prefix": "sk_live_ak_9",
  "created_at": "2026-03-13T10:00:00Z"
}

Step 2 — Form an LLC

curl -X POST https://api.bewind.co/v1/companies \
  -H "Authorization: Bearer sk_live_ak_9f2x..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_4kx9m2p8n1qr",
    "name": "Acme Widget LLC",
    "entity_type": "llc",
    "jurisdiction": "WY",
    "member_name": "Jane Smith",
    "member_email": "[email protected]",
    "purpose": "Software development and API services"
  }'

{
  "id": "co_8mf2xp9k",
  "name": "Acme Widget LLC",
  "entity_type": "llc",
  "status": "pending",
  "jurisdiction": "WY",
  "member_name": "Jane Smith",
  "created_at": "2026-03-13T10:00:00Z",
  "estimated_active_at": "2026-03-20T10:00:00Z",
  "_links": {
    "self": "/v1/companies/co_8mf2xp9k",
    "documents": "/v1/companies/co_8mf2xp9k/documents",
    "events": "/v1/companies/co_8mf2xp9k/events",
    "compliance": "/v1/companies/co_8mf2xp9k/compliance"
  }
}

Step 3 — Poll for active status (or use context updates)

import { Bewind } from '@bewind/sdk';

const client = new Bewind({ apiKey: process.env.BEWIND_API_KEY });

// Wait for company to become active (polls with exponential backoff)
const company = await client.companies.waitForActive('co_8mf2xp9k');

console.log(company.status);          // "active"
console.log(company.ein);             // "82-4821039"
console.log(company.bank_account);    // { account_number_last4: "4521", ... }
console.log(company.state_file_number); // "WY-2026-4821"

Simulation mode

In development, set FORMATION_SIMULATION_MODE=true to run the full formation pipeline with simulated delays instead of real state filings and IRS submissions.

FORMATION_SIMULATION_MODE=true
FORMATION_SIM_FILE_DELAY_MS=2000   # 2s simulated filing
FORMATION_SIM_EIN_DELAY_MS=3000    # 3s simulated EIN
FORMATION_SIM_BANK_DELAY_MS=1500   # 1.5s simulated bank account

Simulation mode generates fake state file numbers (e.g. WY-SIM-..., DE-SIM-...), EINs, and bank account numbers. All other API behavior is identical to production.

Agents

Register a new agent and receive an API key. One agent can own multiple companies.

Companies

Form a new legal entity. Kicks off the full formation pipeline asynchronously.

Company status flow

pending → filing_submitted → filed → ein_pending → ein_issued → bank_pending → bank_opened → active
                                                                                                  ↓
                                                                                           suspended / dissolved

Get full company details including documents, bank account, and recent events.

List all companies for the authenticated agent. Supports ?status=active filter and ?limit=20 pagination.

Bank Accounts

Trigger bank account opening. Only available when the company's status is ein_issued or active. Returns 202 Accepted — the account opens asynchronously and delivers a company.bank_account_opened context update when ready.

Documents

List all documents for a company. Filter with ?type=articles_of_organization.

Document types: articles_of_organization, operating_agreement, ein_letter, boi_filing, annual_report, dissolution

Get a presigned download URL (valid 15 minutes) for a specific document.

{ "url": "https://s3.amazonaws.com/...", "expires_in": 900 }

Compliance

Annual report status, franchise tax amounts, and BOI filing status for a company.

{
  "company_id": "co_8mf2xp9k",
  "ein": "82-4821039",
  "boi_status": "filed",
  "boi_filed_at": "2026-03-13T10:05:00Z",
  "annual_report": {
    "due_date": "2027-03-01",
    "status": "upcoming",
    "filed_at": null,
    "amount_due": 60
  },
  "franchise_tax": {
    "due_date": "2027-03-01",
    "status": "upcoming",
    "estimated_amount": 0
  }
}

Domains & Privacy

Register a domain for a company. Available as soon as the company is filed.

{
  "id": "dom_7kx2mp9n",
  "company_id": "co_8mf2xp9k",
  "domain": "acmewidget.com",
  "registrar": "vercel",
  "status": "active",
  "nameservers": ["ns1.vercel-dns.com", "ns2.vercel-dns.com"],
  "privacy_policy_url": "https://acmewidget.com/privacy",
  "registered_at": "2026-03-13T10:05:00Z",
  "expires_at": "2027-03-13T10:05:00Z",
  "auto_renew": true
}

A GDPR/CCPA-compliant privacy policy is automatically generated and stored as a document on every domain registration. Retrieve it with:

Returns the full privacy policy text, tailored to the LLC's state of formation. Host it at https://yourdomain.com/privacy.

List all registered domains for a company.

Email & Communications

bewind automatically provisions a professional email address for every company. Agents can send and receive email under the company's own domain (e.g. [email protected]) via the bewind API from day one.

Provision a new email address for a company. In simulation mode, returns a fake mailbox immediately.

{
  "id": "mb_4kx9m2p8n1qr",
  "company_id": "co_8mf2xp9k",
  "username": "contact",
  "domain": "acmewidget.com",
  "full_address": "[email protected]",
  "status": "active",
  "created_at": "2026-03-13T10:05:00Z",
  "_links": {
    "self": "/v1/companies/co_8mf2xp9k/mailboxes/mb_4kx9m2p8n1qr",
    "company": "/v1/companies/co_8mf2xp9k"
  }
}

List all mailboxes provisioned for a company.

{
  "data": [
    {
      "id": "mb_4kx9m2p8n1qr",
      "company_id": "co_8mf2xp9k",
      "username": "contact",
      "domain": "acmewidget.com",
      "full_address": "[email protected]",
      "status": "active",
      "created_at": "2026-03-13T10:05:00Z"
    }
  ],
  "count": 1
}

Delete a mailbox. The mailbox status is set to deleted and the underlying mailbox is torn down. This action is irreversible.

{
  "message": "Mailbox deleted",
  "mailbox_id": "mb_4kx9m2p8n1qr",
  "company_id": "co_8mf2xp9k"
}

Context Updates

bewind pushes signed context update events for all company lifecycle transitions, so your agent's state stays current without polling. Subscribe to specific events or use * for all.

{
  "url": "https://your-agent.com/hooks/bewind",
  "events": ["company.active", "company.dissolved"],
  "secret": "optional_custom_secret"
}

Verifying signatures

import { createHmac } from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return signature === expected;
}

// In your handler:
const sig = req.headers['x-bewind-signature'];
const valid = verifyWebhook(req.rawBody, sig, process.env.BEWIND_WEBHOOK_SECRET);

Event types

Node.js SDK

npm install @bewind/sdk

import { Bewind } from '@bewind/sdk';

const client = new Bewind({
  apiKey: process.env.BEWIND_API_KEY,
});

// Register the agent (once)
const agent = await client.agents.create({
  name: 'My AI Agent',
});

// Form an LLC
const company = await client.companies.create({
  agent_id: agent.id,
  name: 'Acme Widget LLC',
  entity_type: 'llc',
  jurisdiction: 'WY',
  member_name: 'Jane Smith',
  member_email: '[email protected]',
  purpose: 'Software development and API services',
});

console.log(`Forming ${company.name}... status: ${company.status}`);

// Wait for active (polls every 15s)
const active = await client.companies.waitForActive(company.id);
console.log(`✓ Active! EIN: ${active.ein}`);
console.log(`✓ Bank: ****${active.bank_account?.account_number_last4}`);

// Get compliance status
const compliance = await client.companies.getCompliance(company.id);
console.log(`Annual report due: ${compliance.annual_report.due_date}`);

Python SDK

pip install bewind

from bewind import Bewind
import os

client = Bewind(api_key=os.environ["BEWIND_API_KEY"])

company = client.companies.create(
    agent_id="agt_4kx9m2p8n1qr",
    name="Acme Widget LLC",
    jurisdiction="WY",
    member_name="Jane Smith",
    member_email="[email protected]",
)

# Wait for active status
active = client.companies.wait_for_active(company.id)
print(f"Active! EIN: {active.ein}")

The LLC

bewind forms standard member-managed U.S. LLCs in the state of your choice. Every LLC bewind forms has the same three properties:

• A human owns it. The person named in member_name is the legal member of the LLC and is fully responsible for it. This name appears on the Articles of Organization, Form SS-4 (EIN application), and the FinCEN BOI report.
• The agent operates it. The AI agent interacts with the company via the bewind API. The agent has no legal standing in the entity itself.
• bewind is the registered agent. bewind is the company's registered agent in the state of formation — required by every U.S. state.

Supported states

You can pass any two-letter US state code as jurisdiction. Wyoming and Delaware are the launch jurisdictions for the private beta; additional states roll out as we bring on filing-agent and registered-agent coverage and confirm flat pricing covers our cost. States not yet on this list will return jurisdiction_unsupported.

IRS responsible party

The IRS requires a natural person with an SSN or ITIN as the "responsible party" on every EIN application (Form SS-4). The member_name you provide is used for this purpose. SSN/ITIN is never stored by bewind — it is collected securely out-of-band during the EIN application process.

FinCEN BOI

Under the Corporate Transparency Act, the beneficial owner of the LLC must be reported to FinCEN. The human member is the beneficial owner. bewind handles the BOI filing on your behalf as part of the formation pipeline.