openapi: 3.1.0
info:
  title: Metal API
  version: '2026-10-18'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-18: 16 operation(s) read from 10 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Metal has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 23
    documentation: -7
    pages-with-code: 10
    pages-read: 10
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-18'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://docs.metal.build
  - https://docs.metal.build/quickstart
  - https://docs.metal.build/authentication
  - https://docs.metal.build/get-tokens
  - https://docs.metal.build/create-presale
  - https://docs.metal.build/get-presales
  - https://docs.metal.build/resolve-presale
  - https://docs.metal.build/get-holders
  - https://docs.metal.build/distribute
  - https://docs.metal.build/get-presale-by-id
servers:
- url: https://api.metal.build
paths:
  /holder/${holderId}:
    get:
      operationId: get_holder_holderId
      tags:
      - Holder
      summary: GET /holder/${holderId}
      x-source: https://docs.metal.build
      parameters:
      - name: holderId
        in: path
        required: true
        schema:
          type: string
      - name: publicKey
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\n `https://api.metal.build/holder/${holderId}?publicKey=${process.env.NEXT_PUBLIC_METAL_API_KEY}`\n )"
  /holder/${userId}/spend:
    post:
      operationId: post_holder_userId_spend
      tags:
      - Holder
      summary: POST /holder/${userId}/spend
      x-source: https://docs.metal.build
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostHolderUseridSpendRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostHolderUseridSpendResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\n `https://api.metal.build/holder/${userId}/spend`,\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n\
          \ 'x-api-key': 'YOUR_SECRET_API_KEY',\n },\n body: JSON.stringify({\n tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',\n\
          \ amount: 123,\n })"
  /holder/${userId}/transfer:
    post:
      operationId: post_holder_userId_transfer
      tags:
      - Holder
      summary: POST /holder/${userId}/transfer
      x-source: https://docs.metal.build
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostHolderUseridTransferRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostHolderUseridTransferResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\n `https://api.metal.build/holder/${userId}/transfer`,\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n\
          \ 'x-api-key': 'YOUR_SECRET_API_KEY',\n },\n body: JSON.stringify({\n tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',\n\
          \ amount: 123,\n toAddress: '0x191d25c061C081583E616d8978eA670f45A12345',\n })"
  /holder/${userId}/withdraw:
    post:
      operationId: post_holder_userId_withdraw
      tags:
      - Holder
      summary: POST /holder/${userId}/withdraw
      x-source: https://docs.metal.build
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostHolderUseridWithdrawRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostHolderUseridWithdrawResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\n `https://api.metal.build/holder/${userId}/withdraw`,\n {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n\
          \ 'x-api-key': 'YOUR_SECRET_API_KEY',\n },\n body: JSON.stringify({\n tokenAddress: '0x191d25c061C081583E616d8978eA670f45A803E5',\n\
          \ amount: 123,\n toAddress: '0x191d25c061C081583E616d8978eA670f45A12345',\n })"
  /holder/{holderaddress}/token/{tokenaddress}:
    get:
      operationId: get_holder_holderaddress_token_tokenaddress
      tags:
      - Holder
      summary: Get Token Balance
      description: Check a holder's balance for a token.
      x-source: https://docs.metal.build/quickstart
      parameters:
      - name: holderaddress
        in: path
        required: true
        schema:
          type: string
      - name: tokenaddress
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHolderHolderaddressTokenTokenaddressResponse'
      x-evidence:
        kind: documentation
  /holder/user123/transactions:
    get:
      operationId: get_holder_user123_transactions
      tags:
      - Holder
      summary: GET /holder/user123/transactions
      x-source: https://docs.metal.build
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHolderUser123TransactionsResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch('https://api.metal.build/holder/user123/transactions', {\n method: 'GET',\n headers: {\n 'x-api-key': 'YOUR_SECRET_API_KEY',\n\
          \ }\n})"
  /merchant/all-tokens:
    get:
      operationId: get_merchant_all_tokens
      tags:
      - Merchant
      summary: GET /merchant/all-tokens
      x-source: https://docs.metal.build
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantAllTokensResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch(\n 'https://api.metal.build/merchant/all-tokens',\n {\n headers: {\n 'x-api-key': 'YOUR_SECRET_API_KEY',\n },\n })"
  /merchant/presale:
    get:
      operationId: get_merchant_presale
      tags:
      - Merchant
      summary: GET /merchant/presale
      x-source: https://docs.metal.build/create-presale
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantPresaleResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl POST api.metal.build/merchant/presale const response = await fetch ( 'https://api.metal.build/merchant/presale' , { \n\
          \ method : 'POST' , \n headers : { \n 'Content-Type' : 'application/json' , \n 'x-api-key' : 'YOUR_SECRET_API_KEY' , \n } , \n body\
          \ : JSON .stringify ({ \n \"name\" : \"Test Presale 1\" , \n \"description\" : \"This is a test presale 1\" , \n \"startTimestamp\"\
          \ : 1748352156 , \n \"endTimestamp\" : 1"
    post:
      operationId: post_merchant_presale
      tags:
      - Merchant
      summary: POST /merchant/presale
      x-source: https://docs.metal.build/create-presale
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMerchantPresaleResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch ( 'https://api.metal.build/merchant/presale' , { \n method : 'POST' , \n headers : { \n 'Content-Type' : 'application/json'\
          \ , \n 'x-api-key' : 'YOUR_SECRET_API_KEY' , \n } , \n body : JSON .stringify ({ \n \"name\" : \"Test Presale 1\" , \n \"description\"\
          \ : \"This is a test presale 1\" , \n \"startTimestamp\" : 1748352156 , \n \"endTimestamp\" : 1748352456 , \n \"targetUsdcAmount\" :\
          \ 1000 , \n \"tokenInfo\" : { \n \"nam"
  /merchant/presale/resolve:
    get:
      operationId: get_merchant_presale_resolve
      tags:
      - Merchant
      summary: GET /merchant/presale/resolve
      x-source: https://docs.metal.build/resolve-presale
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantPresaleResolveResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl POST api.metal.build/merchant/presale/resolve const response = await fetch ( 'https://api.metal.build/merchant/presale/resolve'\
          \ , { \n method : 'POST' , \n headers : { \n 'Content-Type' : 'application/json' , \n 'x-api-key' : 'YOUR_SECRET_API_KEY' , \n } , \n\
          \ body : JSON .stringify ({ \n \"presaleId\" : \"bec1dcbd-9520-4bd2-824c-9861f811160b\" \n }) , \n }) \n const presale = await response\
          \ .json () \n Copy"
    post:
      operationId: post_merchant_presale_resolve
      tags:
      - Merchant
      summary: POST /merchant/presale/resolve
      x-source: https://docs.metal.build/resolve-presale
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMerchantPresaleResolveResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch ( 'https://api.metal.build/merchant/presale/resolve' , { \n method : 'POST' , \n headers : { \n 'Content-Type' : 'application/json'\
          \ , \n 'x-api-key' : 'YOUR_SECRET_API_KEY' , \n } , \n body : JSON .stringify ({ \n \"presaleId\" : \"bec1dcbd-9520-4bd2-824c-9861f811160b\"\
          \ \n })"
  /merchant/presales:
    get:
      operationId: get_merchant_presales
      tags:
      - Merchant
      summary: GET /merchant/presales
      x-source: https://docs.metal.build/get-presales
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantPresalesResponse'
      x-evidence:
        kind: code-example
        language: javascript
        snippet: "fetch ( \n 'https://api.metal.build/merchant/presales' , \n { \n headers : { \n 'x-api-key' : 'YOUR_SECRET_API_KEY' , \n } ,\
          \ \n })"
  /token/0x1234567890abcdef1234567890abcdef12345678/distribute:
    get:
      operationId: get_token_0x1234567890abcdef1234567890abcdef12345678_distribute
      tags:
      - Token
      summary: GET /token/0x1234567890abcdef1234567890abcdef12345678/distribute
      x-source: https://docs.metal.build/distribute
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetToken0X1234567890Abcdef1234567890Abcdef12345678Distribute'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl POST api.metal.build/token/:tokenAddress/distribute const response = await fetch ( \n 'https://api.metal.build/token/0x1234567890abcdef1234567890abcdef12345678/distribute'\
          \ , \n { \n method : 'POST' , \n headers : { \n 'Content-Type' : 'application/json' , \n 'x-api-key' : 'YOUR_SECRET_API_KEY' , \n }\
          \ , \n body : JSON .stringify ({ \n sendToAddress : '0xabcdef1234567890abcdef1234567890abcdef12' , \n amo"
  /token/{tokenaddress}:
    get:
      operationId: get_token_tokenaddress
      tags:
      - Token
      summary: Get Token
      description: Retrieve token information and holders.
      x-source: https://docs.metal.build/quickstart
      parameters:
      - name: tokenaddress
        in: path
        required: true
        schema:
          type: string
      - name: publicKey
        in: query
        required: true
        schema:
          type: string
        description: Your public API key.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokenTokenaddressResponse'
      x-evidence:
        kind: documentation
  /token/{tokenaddress}/distribute:
    post:
      operationId: post_token_tokenaddress_distribute
      tags:
      - Token
      summary: Distribute Tokens
      description: Distribute tokens to a holder address.
      x-source: https://docs.metal.build
      parameters:
      - name: tokenaddress
        in: path
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        required: true
        schema:
          type: string
        description: YOUR_SECRET_API_KEY
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
        description: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostTokenTokenaddressDistributeRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/conversations:
    get:
      operationId: get_v1_conversations
      tags:
      - Conversations
      summary: GET /v1/conversations
      x-source: https://docs.metal.build/authentication
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl: \n Example request with basic auth curl https://api.protocol.chat/v1/conversations  -u username:password \n Copy Copied!\
          \ \n Please don't commit your Protocol password to GitHub! \n OAuth2 with bearer token \n The recommended way to authenticate with the\
          \ Protocol API is by using OAuth2. When establishing a connection using OAuth2, you will need your access token — you will find it in\
          \ the Protocol "
components:
  schemas:
    PostHolderUseridSpendRequest:
      type: object
      properties:
        tokenAddress:
          type: string
        amount:
          type: integer
    PostHolderUseridSpendResponse:
      type: object
      properties:
        method:
          type: string
        headers:
          type: object
          properties:
            Content-Type:
              type: string
            x-api-key:
              type: string
    PostHolderUseridTransferRequest:
      type: object
      properties:
        tokenAddress:
          type: string
        amount:
          type: integer
        toAddress:
          type: string
    PostHolderUseridTransferResponse:
      type: object
      properties:
        method:
          type: string
        headers:
          type: object
          properties:
            x-api-key:
              type: string
    PostHolderUseridWithdrawRequest:
      type: object
      properties:
        tokenAddress:
          type: string
        amount:
          type: integer
        toAddress:
          type: string
    PostHolderUseridWithdrawResponse:
      type: object
      properties:
        method:
          type: string
        headers:
          type: object
          properties:
            x-api-key:
              type: string
    GetHolderHolderaddressTokenTokenaddressResponse:
      type: object
      properties:
        name:
          type: string
        symbol:
          type: string
        id:
          type: string
        address:
          type: string
        balance:
          type: integer
        value:
          type: number
    GetHolderUser123TransactionsResponse:
      type: object
      properties:
        method:
          type: string
        headers:
          type: object
          properties:
            x-api-key:
              type: string
    GetMerchantAllTokensResponse:
      type: object
      properties:
        headers:
          type: object
          properties:
            x-api-key:
              type: string
    GetMerchantPresaleResponse:
      type: object
      properties:
        Content-Type:
          type: string
        x-api-key:
          type: string
    PostMerchantPresaleResponse:
      type: object
      properties:
        Content-Type:
          type: string
        x-api-key:
          type: string
    GetMerchantPresaleResolveResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        participants:
          type: array
          items: {}
    PostMerchantPresaleResolveResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        participants:
          type: array
          items: {}
    GetMerchantPresalesResponse:
      type: object
      properties:
        headers:
          type: object
          properties:
            x-api-key:
              type: string
    GetToken0X1234567890Abcdef1234567890Abcdef12345678Distribute:
      type: object
      properties:
        success:
          type: boolean
    GetTokenTokenaddressResponse:
      type: object
      properties:
        id:
          type: string
        address:
          type: string
        name:
          type: string
        symbol:
          type: string
        totalSupply:
          type: integer
        startingAppSupply:
          type: integer
        remainingAppSupply:
          type: integer
        merchantSupply:
          type: integer
        merchantAddress:
          type: string
        price:
          type: string
        holders:
          type: array
          description: Array of holder objects
    PostTokenTokenaddressDistributeRequest:
      type: object
      properties:
        sendToAddress:
          type: string
          description: Holder address to receive tokens
        amount:
          type: string
          description: Amount of tokens to distribute
      required:
      - sendToAddress
      - amount
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
security:
- apiKey: []
tags:
- name: Conversations
- name: Holder
- name: Merchant
- name: Token