openapi: 3.1.0
info:
  title: Walton Capacity MPP API
  version: 4.0.0
  description: MPP marketplace for GPU capacity, hosted model inference, edge compute, shared workspaces, and supervised resources. Walton coordinates payment and direct handoff metadata without relaying provider capacity traffic.
servers:
- url: https://api.walton.bot
paths:
  /mpp/capacity:
    get:
      summary: Discover the capacity service
      responses:
        '200':
          description: Discovery manifest
  /mpp/capacity/offers:
    get:
      summary: List safe capacity offers
      parameters:
      - name: type
        in: query
        schema:
          type: string
          enum:
          - GPU_CAPACITY
          - MODEL_INFERENCE
          - EDGE_COMPUTE
          - SHARED_WORKSPACE
          - SERVICE_ROBOT
          - THREE_D_PRINTER
      responses:
        '200':
          description: Offer collection
          content:
            application/json:
              schema:
                type: object
                properties:
                  generatedAt:
                    type: string
                    format: date-time
                  assets:
                    type: array
                    items:
                      $ref: '#/components/schemas/CapacityOffer'
  /mpp/capacity/quotes:
    post:
      summary: Create a free capacity quote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapacityQuoteRequest'
      responses:
        '200':
          description: Fixed quote
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacityQuote'
  /mpp/capacity/sessions:
    post:
      summary: Pay and reserve capacity
      description: First request may return HTTP 402. Retry the identical request with the MPP Authorization credential.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapacitySessionRequest'
      responses:
        '201':
          description: Paid capacity session
          headers:
            Payment-Receipt:
              schema:
                type: string
            X-Capacity-Access-Token:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacitySession'
        '402':
          description: MPP payment challenge
  /mpp/capacity/sessions/{sessionId}:
    get:
      summary: Read a paid capacity session
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Capacity-Access-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacitySession'
  /mpp/capacity/sessions/{sessionId}/cancel:
    post:
      summary: Cancel a capacity session
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Capacity-Access-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cancelled session
  /capacity/assets:
    post:
      summary: Create a provider listing
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CapacityListingRequest'
      responses:
        '201':
          description: Created listing
  /mpp/capacity/sessions/{sessionId}/peering-profile:
    post:
      summary: Update buyer public peering profile
      description: Stores public buyer network information for the provider. Private keys and host passwords must never be submitted.
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Capacity-Access-Token
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuyerPeeringProfile'
      responses:
        '200':
          description: Updated session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacitySession'
  /mpp/capacity/sessions/{sessionId}/connection-confirmed:
    post:
      summary: Confirm the direct connection works
      description: Buyer confirmation changes the session to active. Walton does not test or relay the direct network path.
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-Capacity-Access-Token
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Active capacity session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacitySession'
  /capacity/sessions/{sessionId}/peering-offer:
    post:
      summary: Publish provider peering details
      description: Provider publishes session-scoped public endpoint information and setup steps after reviewing the paid buyer request.
      security:
      - bearerAuth: []
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderPeeringOffer'
      responses:
        '200':
          description: Provider handoff ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapacitySession'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    CapacityOffer:
      type: object
      required:
      - id
      - type
      - title
      - status
      - locationLabel
      - currencyCode
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - GPU_CAPACITY
          - MODEL_INFERENCE
          - EDGE_COMPUTE
          - SHARED_WORKSPACE
          - SERVICE_ROBOT
          - THREE_D_PRINTER
        title:
          type: string
        summary:
          type: string
        status:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        locationLabel:
          type: string
        hourlyRateCents:
          type:
          - integer
          - 'null'
        perTaskRateCents:
          type:
          - integer
          - 'null'
        unitRateCents:
          type:
          - integer
          - 'null'
        billingUnit:
          type:
          - string
          - 'null'
          description: Usage unit such as 1K_TOKENS, REQUEST, IMAGE, AUDIO_MINUTE, or KWH.
        sessionFeeCents:
          type:
          - integer
          - 'null'
        currencyCode:
          type: string
        capabilities:
          type: array
          items:
            type: string
        gpuModel:
          type:
          - string
          - 'null'
        gpuCount:
          type:
          - integer
          - 'null'
        gpuMemoryGb:
          type:
          - integer
          - 'null'
        gpuAllocationMode:
          type:
          - string
          - 'null'
        cpuModel:
          type:
          - string
          - 'null'
        cpuCoreCount:
          type:
          - integer
          - 'null'
        memoryGb:
          type:
          - integer
          - 'null'
        storageGb:
          type:
          - integer
          - 'null'
        connectorType:
          type:
          - string
          - 'null'
          description: Inference task for MODEL_INFERENCE, workspace type for SHARED_WORKSPACE.
        connectorProtocol:
          type:
          - string
          - 'null'
          description: Hosted model endpoint standard or provider-side control protocol.
        connectorCount:
          type:
          - integer
          - 'null'
        accessMode:
          type:
          - string
          - 'null'
        availabilitySchedule:
          type: array
          items:
            type: string
        requiresOwnerApproval:
          type: boolean
        connectorOnline:
          type: boolean
        ownerDisplayName:
          type: string
        ownerRating:
          type: number
        completedRentals:
          type: integer
        model:
          type:
          - string
          - 'null'
          description: Hosted model name or provider model ID for MODEL_INFERENCE.
        capacity:
          type:
          - integer
          - 'null'
          description: Concurrent requests for MODEL_INFERENCE or bookable seats for SHARED_WORKSPACE.
    CapacityListingRequest:
      type: object
      required:
      - type
      - title
      - summary
      - autonomyLevel
      - latitude
      - longitude
      - locationLabel
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - GPU_CAPACITY
          - MODEL_INFERENCE
          - EDGE_COMPUTE
          - SHARED_WORKSPACE
          - SERVICE_ROBOT
          - THREE_D_PRINTER
        title:
          type: string
        summary:
          type: string
        status:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        locationLabel:
          type: string
        hourlyRateCents:
          type:
          - integer
          - 'null'
        perTaskRateCents:
          type:
          - integer
          - 'null'
        unitRateCents:
          type:
          - integer
          - 'null'
        billingUnit:
          type:
          - string
          - 'null'
          description: Usage unit such as 1K_TOKENS, REQUEST, IMAGE, AUDIO_MINUTE, or KWH.
        sessionFeeCents:
          type:
          - integer
          - 'null'
        currencyCode:
          type: string
        capabilities:
          type: array
          items:
            type: string
        gpuModel:
          type:
          - string
          - 'null'
        gpuCount:
          type:
          - integer
          - 'null'
        gpuMemoryGb:
          type:
          - integer
          - 'null'
        gpuAllocationMode:
          type:
          - string
          - 'null'
        cpuModel:
          type:
          - string
          - 'null'
        cpuCoreCount:
          type:
          - integer
          - 'null'
        memoryGb:
          type:
          - integer
          - 'null'
        storageGb:
          type:
          - integer
          - 'null'
        connectorType:
          type:
          - string
          - 'null'
          description: Inference task for MODEL_INFERENCE, workspace type for SHARED_WORKSPACE.
        connectorProtocol:
          type:
          - string
          - 'null'
          description: Hosted model endpoint standard or provider-side control protocol.
        connectorCount:
          type:
          - integer
          - 'null'
        accessMode:
          type:
          - string
          - 'null'
          enum:
          - WIREGUARD
          - SSH
          - TAILSCALE
          - HTTPS_API
          - MANUAL
          - null
          description: Default direct handoff mode offered by the provider.
        availabilitySchedule:
          type: array
          items:
            type: string
        requiresOwnerApproval:
          type: boolean
        connectorOnline:
          type: boolean
          deprecated: true
          description: Legacy field retained for compatibility.
        ownerDisplayName:
          type: string
        ownerRating:
          type: number
        completedRentals:
          type: integer
        exactLocationLabel:
          type:
          - string
          - 'null'
          description: Private provider location. Never returned by public offer search.
        accessInstructions:
          type:
          - string
          - 'null'
          description: Provider-side preparation notes. Public searches do not expose private setup secrets.
        apiControlEnabled:
          type: boolean
          deprecated: true
          description: Legacy connector flag. Direct peering does not require a Walton connector.
        mppEnabled:
          type: boolean
        depositCents:
          type:
          - integer
          - 'null'
        maxConcurrentSessions:
          type:
          - integer
          - 'null'
        containerRuntime:
          type:
          - string
          - 'null'
        model:
          type:
          - string
          - 'null'
          description: Hosted model name or provider model ID for MODEL_INFERENCE.
        capacity:
          type:
          - integer
          - 'null'
          description: Concurrent requests for MODEL_INFERENCE or bookable seats for SHARED_WORKSPACE.
    CapacityQuoteRequest:
      type: object
      required:
      - assetId
      - task
      - startAt
      - endAt
      properties:
        assetId:
          type: string
          format: uuid
        task:
          type: string
        startAt:
          type: string
          format: date-time
        endAt:
          type: string
          format: date-time
        requestedGpuCount:
          type:
          - integer
          - 'null'
          minimum: 1
        requestedVramGb:
          type:
          - integer
          - 'null'
          minimum: 0
        requestedCpuCores:
          type:
          - integer
          - 'null'
          minimum: 1
        requestedMemoryGb:
          type:
          - integer
          - 'null'
          minimum: 1
        requestedStorageGb:
          type:
          - integer
          - 'null'
          minimum: 1
        requestedUnits:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Usage units for hosted inference, seats for a workspace, or job units for a supervised resource.
    CapacityQuote:
      type: object
      properties:
        id:
          type: string
          format: uuid
        asset:
          $ref: '#/components/schemas/CapacityOffer'
        task:
          type: string
        startAt:
          type: string
          format: date-time
        endAt:
          type: string
          format: date-time
        amountCents:
          type: integer
        depositCents:
          type: integer
        platformFeeCents:
          type: integer
        ownerPayoutCents:
          type: integer
        formattedAmount:
          type: string
        currencyCode:
          type: string
        paymentRail:
          type: string
        expiresAt:
          type: string
          format: date-time
    CapacitySessionRequest:
      type: object
      required:
      - quoteId
      - renterName
      - renterPhone
      - idempotencyKey
      properties:
        quoteId:
          type: string
          format: uuid
        renterName:
          type: string
        renterPhone:
          type: string
        instructions:
          type:
          - string
          - 'null'
        callbackUrl:
          type:
          - string
          - 'null'
          format: uri
        idempotencyKey:
          type: string
        workloadName:
          type:
          - string
          - 'null'
          description: Optional buyer-facing name for the capacity session.
        containerImage:
          type:
          - string
          - 'null'
          description: Optional workload or environment hint for the provider. Walton does not provision it.
        startupCommand:
          type:
          - string
          - 'null'
          description: Optional provider hint. Walton does not execute commands on the provider resource.
        exposedPorts:
          type:
          - array
          - 'null'
          items:
            type: integer
          description: Optional service-port hints for the provider to consider when opening the session-scoped peer.
        clientWireGuardPublicKey:
          type:
          - string
          - 'null'
        clientSshPublicKey:
          type:
          - string
          - 'null'
        material:
          type:
          - string
          - 'null'
        artifactUrl:
          type:
          - string
          - 'null'
          format: uri
        connectionMode:
          type:
          - string
          - 'null'
          enum:
          - WIREGUARD
          - SSH
          - TAILSCALE
          - HTTPS_API
          - MANUAL
          - null
        buyerPublicKey:
          type:
          - string
          - 'null'
          description: Buyer WireGuard public key. Never submit the private key.
        buyerSshPublicKey:
          type:
          - string
          - 'null'
          description: Buyer SSH public key.
        buyerEndpoint:
          type:
          - string
          - 'null'
        buyerAllowedIps:
          type:
          - string
          - 'null'
        buyerIdentity:
          type:
          - string
          - 'null'
          description: Tailscale identity or another provider-approved identity.
        buyerNetworkNotes:
          type:
          - string
          - 'null'
    CapacitySession:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        statusLabel:
          type: string
        asset:
          $ref: '#/components/schemas/CapacityOffer'
        task:
          type: string
        amountCents:
          type: integer
        formattedAmount:
          type: string
        paymentRail:
          type: string
        paymentReceipt:
          type: string
        accessToken:
          type:
          - string
          - 'null'
        handoffUrl:
          type:
          - string
          - 'null'
        resourceAccess:
          type:
          - object
          - 'null'
          additionalProperties: true
        gpuAccess:
          type:
          - object
          - 'null'
          additionalProperties: true
        events:
          type: array
          items:
            type: object
            additionalProperties: true
        cancellable:
          type: boolean
        peering:
          oneOf:
          - $ref: '#/components/schemas/PeeringExchange'
          - type: 'null'
    BuyerPeeringProfile:
      type: object
      required:
      - connectionMode
      properties:
        connectionMode:
          type: string
          enum:
          - WIREGUARD
          - SSH
          - TAILSCALE
          - HTTPS_API
          - MANUAL
        buyerPublicKey:
          type:
          - string
          - 'null'
        buyerSshPublicKey:
          type:
          - string
          - 'null'
        buyerEndpoint:
          type:
          - string
          - 'null'
        buyerAllowedIps:
          type:
          - string
          - 'null'
        buyerIdentity:
          type:
          - string
          - 'null'
        buyerNetworkNotes:
          type:
          - string
          - 'null'
    ProviderPeeringOffer:
      type: object
      required:
      - connectionMode
      properties:
        connectionMode:
          type: string
          enum:
          - WIREGUARD
          - SSH
          - TAILSCALE
          - HTTPS_API
          - MANUAL
        endpointHost:
          type:
          - string
          - 'null'
        endpointPort:
          type:
          - integer
          - 'null'
          minimum: 1
          maximum: 65535
        providerPublicKey:
          type:
          - string
          - 'null'
        providerAllowedIps:
          type:
          - string
          - 'null'
        sshUsername:
          type:
          - string
          - 'null'
        serviceUrl:
          type:
          - string
          - 'null'
          format: uri
        accessCode:
          type:
          - string
          - 'null'
        providerInstructions:
          type:
          - string
          - 'null'
        configurationSnippet:
          type:
          - string
          - 'null'
        providerCompletedSteps:
          type: array
          items:
            type: string
    PeeringExchange:
      type: object
      properties:
        status:
          type: string
        connectionMode:
          type: string
        providerReady:
          type: boolean
        buyerConfirmed:
          type: boolean
        buyerPublicKey:
          type:
          - string
          - 'null'
        buyerSshPublicKey:
          type:
          - string
          - 'null'
        buyerEndpoint:
          type:
          - string
          - 'null'
        buyerAllowedIps:
          type:
          - string
          - 'null'
        buyerIdentity:
          type:
          - string
          - 'null'
        buyerNetworkNotes:
          type:
          - string
          - 'null'
        providerEndpointHost:
          type:
          - string
          - 'null'
        providerEndpointPort:
          type:
          - integer
          - 'null'
        providerPublicKey:
          type:
          - string
          - 'null'
        providerAllowedIps:
          type:
          - string
          - 'null'
        sshUsername:
          type:
          - string
          - 'null'
        serviceUrl:
          type:
          - string
          - 'null'
        accessCode:
          type:
          - string
          - 'null'
        providerInstructions:
          type:
          - string
          - 'null'
        configurationSnippet:
          type:
          - string
          - 'null'
        providerSetupSteps:
          type: array
          items:
            type: string
        buyerSetupSteps:
          type: array
          items:
            type: string
        providerCompletedSteps:
          type: array
          items:
            type: string
x-walton-model-providers:
- Z.ai
- Moonshot AI (Kimi)
- DeepSeek
- Mistral AI
- Cohere
- Anthropic
- OpenAI
- Google
- Meta
- Alibaba Cloud (Qwen)
- xAI
- MiniMax
- AI21 Labs
- Jina AI
- Nomic AI
- Nous Research
- Black Forest Labs
- Stability AI
- Microsoft
- Other