Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

alpaca-broker-account-onboarding

Open and manage brokerage accounts via the Alpaca Broker API — account creation, KYC/CIP, identity & disclosures, agreements, document upload (incl. W-8BEN), account status lifecycle, and account updates/closure. Use when a developer is building onboarding, KYC, or account-management flows on Alpaca in any language.

alpacahq · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add alpacahq/alpaca-skills --skill alpaca-broker-account-onboarding

About this skill


name: alpaca-broker-account-onboarding description: Open and manage brokerage accounts via the Alpaca Broker API — account creation, KYC/CIP, identity & disclosures, agreements, document upload (incl. W-8BEN), account status lifecycle, and account updates/closure. Use when a developer is building onboarding, KYC, or account-management flows on Alpaca in any language.

Alpaca Broker API — Account Onboarding & KYC

Create and manage end-user brokerage accounts under your firm. This is the first step of any Broker API integration: no funding, journaling, or trading can happen until an account reaches ACTIVE.

Read alpaca-broker-integration first for base URLs, auth, and conventions. This skill assumes Broker API + HTTP Basic auth.

Reference

  • Guide: https://docs.alpaca.markets/docs/getting-started-with-broker-api, https://docs.alpaca.markets/docs/accounts
  • API ref: https://docs.alpaca.markets/reference/createaccount
  • Live schema: alpaca-docs MCP → get-endpoint title "Broker API" path /v1/accounts

1. Endpoints

MethodPathPurpose
POST/v1/accountsCreate account (submit application)
GET/v1/accountsList/query accounts (returns up to 1000)
GET/v1/accounts/{account_id}Get one account (AccountExtended)
PATCH/v1/accounts/{account_id}Update account
POST/v1/accounts/{account_id}/actions/closeClose account (returns 204)
POST/v1/accounts/{account_id}/documents/uploadUpload owner/KYC documents (array body)
GET/v1/accounts/{account_id}/documentsList uploaded documents
POST / GET/v1/accounts/{account_id}/cipSubmit / retrieve CIP results
GET/v1/country-infoSupported-country data
GET/v1/events/accounts/statusSSE stream of account-status changes → see alpaca-broker-sse-events

2. Create-account request (POST /v1/accounts)

Four objects are required: contact, identity, disclosures, agreements. documents and trusted_contact are optional but usually needed for KYC.

{
  "contact": {
    "email_address": "jane@example.com",
    "phone_number": "+15555555555",
    "street_address": ["20 N San Mateo Dr"],
    "city": "San Mateo",
    "state": "CA",            // required if country / country_of_tax_residence is USA
    "postal_code": "94401",
    "country": "USA"          // ISO 3166-1 alpha-3
  },
  "identity": {
    "given_name": "Jane",
    "family_name": "Doe",
    "date_of_birth": "1990-01-01",
    "tax_id_type": "USA_SSN", // see enum below
    "tax_id": "666-55-4321",
    "country_of_tax_residence": "USA",
    "funding_source": ["employment_income"]
  },
  "disclosures": {
    "is_control_person": false,
    "is_affiliated_exchange_or_finra": false,
    "is_politically_exposed": false,
    "immediate_family_exposed": false
  },
  "agreements": [
    { "agreement": "customer_agreement", "signed_at": "2026-01-02T18:09:33Z", "ip_address": "185.13.21.99" }
  ],
  "documents": [ /* OwnerDocumentUploadRequest[] — see §4 */ ],
  "trusted_contact": { "given_name": "Jim", "family_name": "Doe", "email_address": "jim@example.com" }
}

Key field rules:

  • contact.street_address is an array (max 3 lines). contact.state required when country/tax-residence is USA.
  • identity.funding_source is an array; one+ of employment_income, investments, inheritance, business_income, savings, family.
  • tax_id_type enum is large and country-specific: USA_SSN, USA_ITIN, IND_PAN, MEX_RFC, GBR_NINO, … plus generic NATIONAL_ID, PASSPORT, DRIVER_LICENSE, OTHER_GOV_ID, NOT_SPECIFIED. Query the spec for the full list rather than hardcoding.
  • Optional top-level: account_type (trading|custodial|donor_advised|ira), account_sub_type (IRA: traditional|roth), enabled_assets (us_equity|us_option|crypto|ipo, default us_equity).
  • Deprecated: investment_objective/investment_time_horizon/liquidity_needs/risk_tolerance moved from identity to top-level.

Responses: 200 → account object · 409 email already registered · 422 invalid value · 400 malformed body.

3. Agreements

Each entry: agreement (customer_agreement, account_agreement, margin_agreement, crypto_agreement, options_agreement), signed_at (RFC3339), ip_address (IPv4), optional revision. You must present the agreement text to the user and capture the real signing timestamp + IP — Alpaca treats these as the legal record. revision defaults to the currently-active revision if omitted.

4. Documents & W-8BEN

documents[] items: document_type + (content base64 or content_data).

{ "document_type": "identity_verification", "content": "<base64>", "mime_type": "image/jpeg", "document_sub_type": "passport" }
  • document_type enum includes identity_verification, address_verification, date_of_birth_verification, tax_id_verification, w8ben, w9, cip_result, and more.
  • mime_type: application/pdf, image/png, image/jpeg — plus application/json only for w8ben.
  • W-8BEN shortcut (lesson): instead of generating a PDF, upload content_data as a structured W8benDocument JSON object (full_name, country_citizen, permanent_address_*, date_of_birth, ip_address, timestamp, signer_full_name, …) and Alpaca renders the official form for you. This is the clean way to satisfy the tax-form requirement for non-US persons programmatically.
  • Doc size cap: 10 MB per file when using Alpaca's KYC-as-a-service; no cap if you run your own KYC.

5. Account status lifecycle

status (and crypto_status) use the AccountStatus enum:

StatusMeaning
ONBOARDINGApplication expected, not yet submitted
SUBMITTEDSubmitted, being processed
SUBMISSION_FAILEDSubmission error
ACTION_REQUIREDNeeds manual action (e.g. a true disclosure r
Read the complete source ↗