swagger.yaml

swagger: '2.0'

info:
  version: "0.1.0"
  title: Bitcoin payment channel REST protocol
  description: |
    A RESTful protocol for opening, closing and making payments over a Bitcoin payment channel. The payment server speaking this protocol is the recipient of value, operating on behalf of a content delivery server who receives value from a customer/client.
  
    The content delivery server passes requests supplied by the client (payer) to the payment server, and delivers content to the client dependent on the response from the payment server. The client, on its side, derives a state object from the supplied arguments, using a client-side payment channel library, which is used to format messages and create payments.'
host: localhost
basePath: /v1
schemes:
  - http

paths:
  /fundingInfo:
    get:
      summary: Retrieve information about how to fund a new payment channel.
      description: 'Example URL: http://pay.example.com/fundingInfo?client_pubkey=029b5549e8cac42d27051956925d8176408b2183ba357850f58320ad5876b9c13f&exp_time=1464300843'
      operationId: getFundingInfo
      parameters:
        - $ref: "#/parameters/clientPubKeyParam"
        - $ref: "#/parameters/expTimeParam"
      responses:
        200:
          description: Proceed with funding
          schema:
            $ref: "#/definitions/FundingInfo"
        400:
          description: Invalid input (see header for error description)
  
  /channels/new:
    post:
      summary: Create a new payment channel
      description: 'Example URL: http://pay.example.com/channels/new?client_pubkey=029b5549e8cac42d27051956925d8176408b2183ba357850f58320ad5876b9c13f&exp_time=1464300843'
      operationId: createPaymentChannel
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/clientPubKeyParam"
        - $ref: "#/parameters/expTimeParam"
        - in: body
          name: payment
          description: 'Channel payment. When making a payment: new payment. When deleting a channel: most recently transmitted channel payment.'
          required: true
          schema:
            $ref: "#/definitions/Payment"
      responses:
        201:
          description: Channel created
          schema:
            $ref: "#/definitions/ChanOpenResult"
        400:
          description: Invalid input (see header for error description)
          
  /channels/{funding_txid}/{funding_vout}:
    parameters:
      - $ref: "#/parameters/fundingTxIdParam"
      - $ref: "#/parameters/fundingTxVoutParam"
      - in: body
        name: payment
        description: 'Channel payment. When making a payment: new payment. When deleting a channel: most recently transmitted channel payment.'
        required: true
        schema:
          $ref: "#/definitions/Payment"
    put:
      summary: Make payment over an existing payment channel
      description: 'Example URL: http://pay.example.com/channels/f4cfa4a18d474d7e7c7d18edbb5c9c37293eea1136d2a01788342211c5e3d3f0/3?change_address=1Cu5XbSFuvrmVDc95Yj87cTHYPgePievmN'
      operationId: payPaymentChannel
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        200:
          description: Payment received
          schema:
            $ref: "#/definitions/PaymentResult"
        400:
          description: Invalid input (see header for error description)
        404:
          description: No such payment channel
    delete:
      summary: Delete an existing payment channel
      description: 'Example URL: http://pay.example.com/channels/f4cfa4a18d474d7e7c7d18edbb5c9c37293eea1136d2a01788342211c5e3d3f0/3'
      operationId: deletePaymentChannel
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        200:
          description: Channel closed, funds settled. The settling transaction has been published to the Bitcoin network.
        400:
          description: Invalid input (see header for error description)
        404:
          description: No such payment channel

parameters:
    clientPubKeyParam:
      name: client_pubkey
      in: query
      description: Client/value sender public key (33-byte, hex-encoded, compressed Secp256k1 pubkey)
      required: true
      type: string
      # example: '029b5549e8cac42d27051956925d8176408b2183ba357850f58320ad5876b9c13f'
    expTimeParam:
      name: exp_time
      in: query
      description: The expiration date/time for the channel (Unix timestamp). After this point in time the channel refund transaction becomes valid, allowing the client to reclaim the channel funds in case the server goes missing.
      required: true
      type: integer
      format: int64
    fundingTxIdParam:
      name: funding_txid
      in: path
      description: Transaction ID of the transaction which pays to the channel funding address.
      required: true
      type: string
    fundingTxVoutParam:
      name: funding_vout
      in: path
      description: Output index/vout of the output in the transaction paying to the channel funding address.
      required: true
      type: string
      
definitions:
  FundingInfo:
    type: object
    required:
      - server_pubkey
      - funding_address
      - channel_open_uri
      - open_price
      - funding_tx_min_conf
    properties:
      server_pubkey:
        description: Server public key (33-byte, hex-encoded, compressed Secp256k1 pubkey)
        type: string
        example: "029b5549e8cac42d27051956925d8176408b2183ba357850f58320ad5876b9c13f"
      funding_address:
        description: Payment channel funding address. Send bitcoins to this address to fund a new channel.
        type: string
        example: "2NCTirSGjFM8T7hUow3AcfyFaw1N1APnYuP"
      channel_open_uri:
        description: The URI which must be POSTed to in order to open a new payment channel. See <<_createpaymentchannel,createPCHTeeest>>.
        type: string
        format: uri
      open_price:
        description: Price (in satoshis) for opening a channel with the given {exp_time}. This amount is paid in the initial channel payment when creating a new channel. May be zero, in which case a payment of zero value is transferred, ensuring that the channel can be closed at any time.
        type: integer
        format: int64
        minimum: 0
        example: 25000
      funding_tx_min_conf:
        description: Minimum confirmation count that the funding transaction must have before proceeding with opening a new channel.
        type: integer
        format: int32 
  ChanOpenResult:
    type: object
    required:
      - channel_uri
      - payment_result
    properties:
      channel_uri:
        description: The URI of the newly opened channel. Payments are PUT on this URI.
        type: string
        format: uri
      payment_result:
        $ref:  "#/definitions/PaymentResult"  
  Payment:
    type: object
    properties:
      payment_data:
        description: Opaque payment data, base64-encoded
        type: string
  PaymentResult:
    type: object
    required:
      - channel_value_left
      - value_received
    properties:
      channel_value_left:
        description: Remaining channel value. This is the amount that the client/sender would receive if the channel was closed now.
        type: integer
        format: int64
        minimum: 0
      value_received:
        description: Value of the payment that was just received. This is the additional value assigned to the receiver/server with this payment.
        type: integer
        format: int64
        minimum: 0