BorgLayer Formation API

openapi: 3.2.0
info:
  title: BorgLayer Formation API
  version: 1.0.0
  description: 'The BorgLayer API lets you — and AI agents, via the BorgLayer MCP connector —

    search and register domains, transfer domains in, manage DNS, set registrant

    details, and form US LLCs, all paid from a prepaid USDC account balance.


    - **Base URL:** `https://api.borglayer.com/api/v1`

    - **MCP connector:** `https://mcp.borglayer.com/mcp` (Streamable HTTP)

    - **Auth:** `Authorization: Bearer blrk_…` on every request


    ## Getting started


    1. Create a BorgLayer account and an API key (format `blrk_…`) in your

    dashboard. Each key has **scopes** that limit what it can do and is bound

    to your account''s prepaid USDC balance.

    2. Call the API with `Authorization: Bearer blrk_…`, or add the MCP connector

    in Claude (**Customize → Connectors → Add custom connector**) with URL

    `https://mcp.borglayer.com/mcp`, Authentication **No sign-in**, and request

    header `Authorization: Bearer blrk_…`.

    3. Top up your prepaid balance in the dashboard. Read actions are free; actions

    that cost money (register, transfer-in, formation) debit your balance.


    ## Money model


    Actions that cost money debit your prepaid USDC balance. If the balance is too

    low the API returns `402 insufficient_balance` and **nothing is charged**.


    ## Scopes


    | Scope | Grants |

    |-------|--------|

    | `domains.read` | search, list your domains |

    | `domains.register` | register a domain (debits balance) |

    | `domains.transfer` | transfer a domain in (may debit balance) |

    | `dns.read` | list DNS records |

    | `dns.write` | add/delete DNS records |

    | `registrant.read` | list registrant profiles |

    | `registrant.write` | create/delete registrant profiles |

    | `formation.read` | quote a formation, read order status |

    | `formation.write` | create (file) a formation (debits balance) |

    | `balance.read` | read your prepaid balance |


    A `403` with `required scope: ` means your key lacks that scope.'
  contact:
    name: BorgLayer
    url: https://borglayer.com
    email: support@borglayer.com
servers:
- url: https://api.borglayer.com/api/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Formation
paths:
  /formation/quote:
    get:
      summary: Quote a US company formation
      description: 'Price a US LLC (or other entity) formation, with optional EIN and BOI add-ons. Your reseller markup (capped at 25%) is applied on top of BorgLayer retail. Scope: `formation.read`.'
      parameters:
      - name: company
        in: query
        required: true
        schema:
          type: string
      - name: state
        in: query
        required: true
        schema:
          type: string
          example: NM
      - name: entity
        in: query
        schema:
          type: string
          default: LLC
      - name: ein
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: boi
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
      responses:
        '200':
          description: 'Quote with add-on breakdown plus reseller pricing: borglayer_retail_micro, reseller_markup_bps, reseller_margin_micro, customer_paid_micro (= retail + your markup).'
      tags:
      - Formation
      operationId: getFormationQuote
      x-operation-id-source: derived
  /formation:
    post:
      summary: Form a US company
      description: 'Form the entity. Debits your balance for BorgLayer retail plus your reseller markup (capped at 25%); you keep the markup as margin. Then files. Scope: `formation.write`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - company
              - state
              - entity
              - contact
              properties:
                company:
                  type: string
                  example: Example Ventures LLC
                state:
                  type: string
                  example: NM
                entity:
                  type: string
                  default: LLC
                contact:
                  $ref: '#/components/schemas/RegistrantProfile'
                ein:
                  type: boolean
                boi:
                  type: boolean
                email:
                  type: string
      responses:
        '201':
          description: '{ reference, status, borglayer_retail_micro, reseller_markup_bps, reseller_margin_micro, customer_paid_micro, balance_micro }'
        '402':
          description: insufficient_balance (nothing charged)
      tags:
      - Formation
      operationId: postFormation
      x-operation-id-source: derived
  /formation/{reference}:
    get:
      summary: Formation order status
      description: 'Scope: `formation.read`.'
      parameters:
      - name: reference
        in: path
        required: true
        schema:
          type: string
          example: stateform_…
      responses:
        '200':
          description: Formation order status
      tags:
      - Formation
      operationId: getFormationByReference
      x-operation-id-source: derived
components:
  schemas:
    RegistrantProfile:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        phone:
          type: string
        address_line1:
          type: string
        city:
          type: string
        postal_code:
          type: string
        country:
          type: string
        organization_name:
          type: string
        is_default:
          type: boolean
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: blrk_…