openapi: 3.1.0
info:
  title: TCP Port Scanner
  description: Give this API a hostname or IP address and it will try connecting to each port in your requested range. For
    every port that answers, it tells you whether it is open or blocked, which service is likely running there (like a web
    server or SSH), and what software version was detected. This saves you from installing network tools, parsing messy command-line
    output, or writing socket loops yourself. Only scan hosts you own or have permission to scan — this tool does not check
    that for you.
  version: 1.0.0
  contact:
    name: _done
    url: https://forms.gle/5KzuSFH7p8hHtDmz7
    email: info@underscoredone.com
  x-openapi-url: https://port-scanner.underscoredone.com/openapi.json
  x-logo:
    url: https://underscoredone.com/logo.png
    altText: _done
  x-guidance: POST a JSON body with 'target' (hostname or IP as a string) and optionally 'ports' (a range like '1-1000' or
    a comma-separated list like '22,80,443'), 'scan_type' (only 'tcp_connect' is supported), and 'timeout' (whole number of
    seconds, 5 to 60). The response includes an 'open_ports' array — each item has 'port', 'protocol', 'state', 'service',
    and 'version'. Use 'ports_scanned' and 'closed_or_filtered_count' for summary stats. If the target cannot be reached or
    resolved, you will receive a 400 error with a plain-English 'error' field. Never use this on hosts you do not own or have
    explicit permission to scan.
  x-ai-instructions: POST a JSON body with 'target' (hostname or IP as a string) and optionally 'ports' (a range like '1-1000'
    or a comma-separated list like '22,80,443'), 'scan_type' (only 'tcp_connect' is supported), and 'timeout' (whole number
    of seconds, 5 to 60). The response includes an 'open_ports' array — each item has 'port', 'protocol', 'state', 'service',
    and 'version'. Use 'ports_scanned' and 'closed_or_filtered_count' for summary stats. If the target cannot be reached or
    resolved, you will receive a 400 error with a plain-English 'error' field. Never use this on hosts you do not own or have
    explicit permission to scan.
  x-provider: _done — single-purpose utility APIs for developers and AI agents. Pay per call with USDC on Base Mainnet or
    Solana Mainnet.
  x-pricing:
    model: pay-per-call
    currency: USDC
    network: Base Mainnet or Solana Mainnet
    price: $0.01
  x-keywords:
  - network
  - port
  - scanner
  - tcp
  - open ports
  - service detection
  - nmap
  - infrastructure
  - security audit
  - firewall check
  - utility
  - api
  - ai-agent
  - pay-per-call
  - usdc
  - x402
  x-category: port scanner
  x-provider-url: https://underscoredone.com
  x-agentcash-auth:
    mode: paid
  x-402:
    price: $0.01
    network: eip155:8453
    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
    pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    facilitator: https://api.cdp.coinbase.com/platform/v2/x402
    scheme: exact
    description: Give this API a hostname or IP address and it will try connecting to each port in your requested range. For
      every port that answers, it tells you whether it is open or blocked, which service is likely running there (like a web
      server or SSH), and what software version was detected. This saves you from installing network tools, parsing messy
      command-line output, or writing socket loops yourself. Only scan hosts you own or have permission to scan — this tool
      does not check that for you.
    mime_type: application/json
    networks:
    - network: eip155:8453
      asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    - network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
      asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
      pay_to: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
paths:
  /scan:
    post:
      tags:
      - port scanner
      - port scan
      - open ports
      - tcp port scanner
      - scan ports
      - port
      - open port check
      - service detection
      - network scanner
      - port check
      - host port scan
      - security scan
      - banner grab
      - ssh port check
      - nmap
      summary: Check which ports on a host are open and what services are listening on them
      description: Check which ports on a host are open and what services are listening on them.
      operationId: scan_scan_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanRequest'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResponse'
              examples:
                success:
                  summary: Successful response
                  value:
                    api_version: 1.0.0
                    target: scanme.nmap.org
                    resolved_ip: 45.33.32.156
                    scan_type: tcp_connect
                    duration_ms: 4521
                    complete: true
                    ports_requested: 1000
                    ports_scanned: 1000
                    open_ports:
                    - port: 22
                      protocol: tcp
                      state: open
                      service: ssh
                      version: OpenSSH 8.2p1
                    - port: 80
                      protocol: tcp
                      state: open
                      service: http
                      version: Apache httpd 2.4.41
                    closed_or_filtered_count: 998
                    warning: null
        '422':
          description: Unprocessable — a required field is missing or the wrong type. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
        '402':
          description: Payment required. Send a signed USDC payment on Base Mainnet or Solana Mainnet using the x402 protocol.
          headers:
            X-Payment-Response:
              description: x402 payment challenge — base64-encoded JSON with payment details.
              schema:
                type: string
        '400':
          description: Bad request — your input failed validation or could not be processed. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      x-ai-instructions: POST a JSON body with 'target' (hostname or IP as a string) and optionally 'ports' (a range like
        '1-1000' or a comma-separated list like '22,80,443'), 'scan_type' (only 'tcp_connect' is supported), and 'timeout'
        (whole number of seconds, 5 to 60). The response includes an 'open_ports' array — each item has 'port', 'protocol',
        'state', 'service', and 'version'. Use 'ports_scanned' and 'closed_or_filtered_count' for summary stats. If the target
        cannot be reached or resolved, you will receive a 400 error with a plain-English 'error' field. Never use this on
        hosts you do not own or have explicit permission to scan.
      x-guidance: POST a JSON body with 'target' (hostname or IP as a string) and optionally 'ports' (a range like '1-1000'
        or a comma-separated list like '22,80,443'), 'scan_type' (only 'tcp_connect' is supported), and 'timeout' (whole number
        of seconds, 5 to 60). The response includes an 'open_ports' array — each item has 'port', 'protocol', 'state', 'service',
        and 'version'. Use 'ports_scanned' and 'closed_or_filtered_count' for summary stats. If the target cannot be reached
        or resolved, you will receive a 400 error with a plain-English 'error' field. Never use this on hosts you do not own
        or have explicit permission to scan.
      x-payment-info:
        price:
          fixed:
            mode: fixed
            currency: USD
            amount: '0.01'
        protocols:
        - x402: {}
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OpenPort:
      properties:
        port:
          type: integer
          title: Port
          description: The port number that is open.
        protocol:
          type: string
          title: Protocol
          description: The network protocol used (always 'tcp' for this scan type).
        state:
          type: string
          title: State
          description: Whether the port is 'open', 'closed', or 'filtered'.
        service:
          type: string
          title: Service
          description: The name of the service most likely running on this port, like 'ssh' or 'http'.
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
          description: The software version detected on this port, if any. May be empty if not detectable.
      type: object
      required:
      - port
      - protocol
      - state
      - service
      title: OpenPort
    ScanRequest:
      properties:
        target:
          type: string
          title: Target
          description: The hostname (like 'example.com') or numeric IP address (like '93.184.216.34') you want to scan. Must
            be a real, reachable address.
        ports:
          anyOf:
          - type: string
          - type: 'null'
          title: Ports
          description: Which ports to check. Use a range like '1-1000', a comma-separated list like '22,80,443', or leave
            this out to automatically check the 1000 most commonly used ports.
        scan_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Scan Type
          description: How to probe each port. The only supported value right now is 'tcp_connect'. Defaults to 'tcp_connect'
            if left out.
          default: tcp_connect
        timeout:
          anyOf:
          - type: integer
            maximum: 60.0
            minimum: 5.0
          - type: 'null'
          title: Timeout
          description: How many seconds the scan is allowed to run before giving up. Must be between 5 and 60. Defaults to
            30 if left out.
          default: 30
      type: object
      required:
      - target
      title: ScanRequest
      example:
        ports: 1-1000
        scan_type: tcp_connect
        target: scanme.nmap.org
        timeout: 30
    ScanResponse:
      properties:
        api_version:
          type: string
          title: Api Version
          description: API version
          default: 1.0.0
        target:
          type: string
          title: Target
          description: The hostname or IP address that was scanned, echoed back from your request.
        resolved_ip:
          type: string
          title: Resolved Ip
          description: The numeric IP address the hostname was resolved to before scanning.
        scan_type:
          type: string
          title: Scan Type
          description: The scan method used.
        duration_ms:
          type: integer
          title: Duration Ms
          description: How long the scan took in milliseconds.
        complete:
          type: boolean
          title: Complete
          description: True if every requested port was scanned. False if the time budget ran out and only part of the range
            was probed — in that case the open_ports listed are still accurate, but ports NOT listed may be unscanned rather
            than closed.
          default: true
        ports_requested:
          type: integer
          title: Ports Requested
          description: How many ports you asked to scan.
        ports_scanned:
          anyOf:
          - type: integer
          - type: 'null'
          title: Ports Scanned
          description: How many ports were actually checked. Equals ports_requested on a complete scan; lower when the scan
            was cut short by the time budget.
        open_ports:
          items:
            $ref: '#/components/schemas/OpenPort'
          type: array
          title: Open Ports
          description: Ports that responded as open, sorted from lowest to highest port number. Always trustworthy, even on
            an incomplete scan.
        closed_or_filtered_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Closed Or Filtered Count
          description: How many scanned ports were closed or blocked. On an incomplete scan this covers only the ports actually
            probed.
        warning:
          anyOf:
          - type: string
          - type: 'null'
          title: Warning
          description: Present only when the scan did not fully complete. Explains what to do for full coverage.
      type: object
      required:
      - target
      - resolved_ip
      - scan_type
      - duration_ms
      - ports_requested
      - open_ports
      title: ScanResponse
      example:
        api_version: 1.0.0
        closed_or_filtered_count: 998
        complete: true
        duration_ms: 4521
        open_ports:
        - port: 22
          protocol: tcp
          service: ssh
          state: open
          version: OpenSSH 8.2p1
        - port: 80
          protocol: tcp
          service: http
          state: open
          version: Apache httpd 2.4.41
        ports_requested: 1000
        ports_scanned: 1000
        resolved_ip: 45.33.32.156
        scan_type: tcp_connect
        target: scanme.nmap.org
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: CAIP-122 wallet signature for repeat access after payment
servers:
- url: https://port-scanner.underscoredone.com
  description: Production
tags:
- name: port scanner
- name: port scan
- name: open ports
- name: tcp port scanner
- name: scan ports
- name: port
- name: open port check
- name: service detection
- name: network scanner
- name: port check
- name: host port scan
- name: security scan
- name: banner grab
- name: ssh port check
- name: nmap
x402Version: 2
x-payment-accepts:
- scheme: exact
  network: eip155:8453
  payTo: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
- scheme: exact
  network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
  payTo: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
  asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v