BorgLayer Marketplace API

openapi: 3.2.0
info:
  title: BorgLayer Marketplace 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: Marketplace
paths:
  /marketplace/listings:
    get:
      summary: Browse marketplace listings
      description: 'Active domains listed for sale, priced in USDC. One unified `blrk_` key does registration AND marketplace. Scope: `marketplace.read`.'
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Active listings (id
          domain_name: null
          price_micro: null
          currency): null
      tags:
      - Marketplace
      operationId: getMarketplaceListings
      x-operation-id-source: derived
  /marketplace/listings/{id}:
    get:
      summary: Marketplace listing detail
      description: 'Scope: `marketplace.read`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The listing
        '404':
          description: not_found
      tags:
      - Marketplace
      operationId: getMarketplaceListingsById
      x-operation-id-source: derived
  /marketplace/checkout:
    post:
      summary: Buy a listed domain (escrow)
      description: 'Create an on-chain escrow to buy a listed domain. BorgLayer takes a 0.99%

        settlement fee on the sale (0.50% credited to your reseller account as

        commission, 0.49% to BorgLayer). Scope: `marketplace.write`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - listing_id
              - buyer_wallet
              properties:
                listing_id:
                  type: string
                  format: uuid
                buyer_wallet:
                  type: string
                  pattern: ^0x[0-9a-fA-F]{40}$
      responses:
        '201':
          description: Escrow created (order_id, escrow_address, chain, token, amount_micro)
        '422':
          description: listing not available
      tags:
      - Marketplace
      operationId: postMarketplaceCheckout
      x-operation-id-source: derived
  /marketplace/orders/{id}:
    get:
      summary: Marketplace order (escrow) status
      description: 'Scope: `marketplace.read`.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Order status
        '404':
          description: not_found
      tags:
      - Marketplace
      operationId: getMarketplaceOrdersById
      x-operation-id-source: derived
  /marketplace/earnings:
    get:
      summary: Your marketplace commission summary
      description: 'Commission (0.50% of each referred/own sale) owed, paid, pending, and sale count. Scope: `marketplace.read`.'
      responses:
        '200':
          description: '{ owed, paid, pending, sales }'
      tags:
      - Marketplace
      operationId: getMarketplaceEarnings
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: blrk_…