openapi: 3.0.2
info: 
  title: Raiden API
  description: https://raiden-network.readthedocs.io/en/latest/rest_api.html
  version: 1.0.0
servers:
  - url: http://127.0.0.1:5001/api/v1
    description: local server
paths: 
  /address: 
    get: 
      summary: "Query your address"
      description: "When raiden starts, you choose an ethereum address which will also be your raiden address."
      tags: 
        - Raiden Node
      operationId: getAddress
      responses: 
        '200': 
          description: "Your ethereum address"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Address'
  /tokens: 
    get:
      summary: "Returns a list of addresses of all registered tokens."
      tags: 
        - Tokens
      operationId: getTokens
      responses:
        '200':
          description: All registered tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /tokens/{token_address}:
    get:
      summary: Address of the corresponding token network 
      description: Returns the address of the corresponding token network for the given token, if the token is registered.
      tags: 
        - Tokens
      operationId: getToken
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address associated with a token network
      responses:
        '200':
          description: The token network address
          content:
            application/json:
              schema:
                type: string
        '404':
          description: No token network found for the provided token address
          content:
            application/json:
              schema:
                type: string
    put: 
      summary: "Registers a token"
      tags: 
        - Tokens
      description: "If a token is not registered yet (i.e.: A token network for that token does not exist in the registry), we need to register it by deploying a token network contract for that token."
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address
      operationId: registerToken
      responses: 
        '201':
          description: "The token network address"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/TokenNetworkAddress'
        '404':
          description: "Token not found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '402':
          description: "Payment Required"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: "Token already registered"
          content:
            application/json:
              schema:
                type: string
                enum: ['Token already registered']
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /tokens/{token_address}/partners:
    get:
      summary: List of all partners with whom you have non-settled channels 
      description: Returns a list of all partners with whom you have non-settled channels for a certain token.
      tags: 
        - Tokens
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address associated with a token network
      operationId: getTokenPartners
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Partner'
  /channels:
    get:
      summary: "List of all unsettled channels"
      tags:
        - Channels
      operationId: getChannels
      responses: 
        '200':
          description: "Unsettled channels"
          content:
            application/json:
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    put:
      summary: Opens a channel
      tags: 
        - Channels
      operationId: openChannel
      requestBody:
        description: "The request’s payload is a channel object; since it is a new channel, its channel_address and status fields will be ignored and can be omitted. The request to the endpoint will later return the fully created channel object."
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelPartial'
      responses:
        '201':
          description: Channel created successfully
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Channel'
        '400':
          description: Provided JSON is in some way malformed
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '402':
          description:  Insufficient ETH to pay for the gas of the channel open on-chain transaction
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '408':
          description: Deposit event was not read in time by the Ethereum node
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '409':
          description: Invalid input, e. g. too low a settle timeout
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'

  /channels/{token_address}: 
    get: 
      summary: "List of all unsettled channels for the given token address."
      tags: 
        - Channels
      operationId: getChannelsForToken
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address to get unsettled channels for
      responses: 
        '200':
          description: "Unsettled channels"
          content:
            application/json:
              schema: 
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /channels/{token_address}/{partner_address}: 
    get: 
      summary: "Query information about one of your channels."
      tags: 
        - Channels
      description: The channel is specified by the address of the token and the partner’s address.
      operationId: getPartnerChannel
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address to get unsettled channels for
        - in: path
          name: partner_address
          schema:
            type: string
          required: true
          description: The partner address
      responses: 
        '200':
          description: "Unsettled channels"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Channel'
        '404':
          description: "The given token and / or partner addresses are not valid eip55-encoded Ethereum addresses, or the channel does not exist"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    patch:
      summary: Close a channel or to increase the deposit in it.
      tags: 
        - Channels
      operationId: patchChannel
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address to get unsettled channels for
        - in: path
          name: partner_address
          schema:
            type: string
          required: true
          description: The partner address
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                total_deposit:
                  $ref: '#/components/schemas/IncreaseDeposit'
                total_withdraw:
                  $ref: '#/components/schemas/IncreaseWithdraw'
                state:
                  type: string
                  enum: ['closed']
                  description: Desired new state
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Channel'
        '400':
          description: "The provided JSON is in some way malformed, or there is nothing to do since none of `state`,`total_deposit` or `total_withdraw` have been given, or: the value of `state` is not a valid channel state."
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '402':
          description:  "Insufficient balance to do a deposit, or insufficient ETH to pay for the gas of the on-chain transaction"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '404':
          description: "The given token and / or partner addresses are not valid [EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded Ethereum addresses"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '408':
          description: "Deposit event was not read in time by the Ethereum node"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '409': 
          description: "Provided channel does not exist or `state`, `total_deposit`, and `total_withdraw` have been attempted to update in the same request or attempt to deposit token amount lower than on-chain balance of the channel attempt to deposit more tokens than the testing limit"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'
        '500':
          description: "Internal Raiden node error"
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/Errors'

  /pending_transfers:
    get:
      summary: "Returns a list of all transfers that have not been completed yet."
      operationId: getPendingTransfers
      tags: 
        - Pending Transfers
      responses:
        '200':
          description: "Transfers that have not been completed"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PendingTransfer'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /pending_transfers/{token_address}:
    get:
      summary: "List of all transfers that have not been completed yet for this token"
      tags: 
        - Pending Transfers
      operationId: getPendingTransfersForToken
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address you want pending transfers for
      responses:
        '200':
          description: "Transfers that have not been completed"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PendingTransfer'
        '404':
          description: "The token was not found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /pending_transfers/{token_address}/{partner_address}:
    get:
      summary: "List of all transfers that have not been completed yet for this token on this channel"
      tags: 
        - Pending Transfers
      operationId: getPendingTransfersForTokenOnChannel
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address you want pending transfers for
        - in: path
          name: partner_address
          schema:
            type: string
          required: true
          description: The token address you want pending transfers for
      responses:
        '200':
          description: "Transfers that have not been completed"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PendingTransfer'
        '404':
          description: "The queried channel or token was not found"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /connections:
    get:
      summary: Query details of all joined token networks.
      description: "The request will return a JSON object where each key is a token address for which you have open channels."
      tags:
        - Connections
      operationId: getConnections
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Connection'
                example:
                  "0x2a65Aca4D5fC5B5C859090a6c34d164135398226":
                    funds: 100
                    sum_deposits: 67
                    channels: 3
                  "0x0f114A1E9Db192502E7856309cc899952b3db1ED":
                    funds: 49
                    sum_deposits: 31
                    channels: 1
        '500':
          description: Internal Raiden node error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /connections/{token_address}:
    put:
      summary: Join a token network.
      description: "The request will only return once all blockchain calls for opening and/or depositing to a channel have completed. <br /> <br /> The request’s payload has `initial_channel_target` and `joinable_funds_target` as optional arguments. If not provided they default to `initial_channel_target = 3` and `joinable_funds_target = 0.4`. <br /><br />If the `initial_channel_target` is bigger than the current number of participants of the token network then the funds will still be split according to the `initial_channel_target` but the number of channels made will be equal to the number of participants in the network. So eventually you will end up with less channels, but each channel will have the expected number of funds allocated to it. The remaining channels will be opened once more peers become available."
      operationId: joinNetwork
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address of the network you want to join
      tags:
        - Connections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelAllocation'
      responses:
        '204':
          description: "Successful connection creation"
        '402':
          description: "If any of the channel deposits fail due to insufficient ETH balance to pay for the gas of the on-chain transactions."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '404':
          description: "The given token address is not a valid [EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded Ethereum address"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '408':
          description: "If a timeout happened during any of the transactions."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: "If any of the provided input to the call is invalid."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: "Internal Raiden node error."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      summary: Leave a token network.
      description: "The request will only return once all blockchain calls for closing/settling a channel have completed."
      operationId: leaveNetwork
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The token address of the network you want to leave
      tags:
        - Connections
      responses:
        '200':
          description: "For successfully leaving a token network"
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: [
                '0x41BCBC2fD72a731bcc136Cf6F7442e9C19e9f313', 
                '0x5A5f458F6c1a034930E45dC9a64B99d7def06D7E', 
                '0x8942c06FaA74cEBFf7d55B79F9989AdfC85C6b85']
        '404':
          description: "The given token address is not a valid [EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded Ethereum address"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: "Internal Raiden node error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /payments:
    get:
      summary: List All Payments
      operationId: getPayments
      tags: 
        - Payments
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentEvent'
        '500':
          description: "Internal Raiden node error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /payments/{token_address}:
    get:
      summary: List All Payments for Token
      operationId: getPaymentsByToken
      tags: 
        - Payments
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The address of the token you want to query
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentEvent'
        '404':
          description: "The given token and / or partner addresses are not valid [EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded Ethereum addresses"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: "If the given block number or token_address arguments are invalid"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: "Internal Raiden node error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /payments/{token_address}/{target_address}:
    get:
      summary: List All Payments for Token by Target
      operationId: getPaymentsByTokenForTarget
      tags: 
        - Payments
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The address of the token you want to query
        - in: path
          name: target_address
          schema:
            type: string
          required: true
          description: The payee address
      responses:
        '200':
          description: Successful query
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentEvent'
        '404':
          description: "The given token and / or partner addresses are not valid [EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded Ethereum addresses"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '409':
          description: "If the given `block number` or `token_address` arguments are invalid"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: "Internal Raiden node error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      summary: Initiate a payment
      description: "The request will only return once the payment either succeeded or failed. A payment can fail due to the expiration of a lock, the target being offline, channels on the path to the target not having enough `settle_timeout` and `reveal_timeout` in order to allow the payment to be propagated safely, not enough funds etc."
      operationId: pay
      parameters:
        - in: path
          name: token_address
          schema:
            type: string
          required: true
          description: The address of the token you want to pay with
        - in: path
          name: target_address
          schema:
            type: string
          required: true
          description: The payee address
      tags: 
        - Payments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: "Successful payment"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentReceipt'
        '400':
          description: "Provided json is in some way malformed"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'  
        '402':
          description: "Payment can’t start due to insufficient balance"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'  
        '408':
          description: "Timeout happened during the payment"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'  
        '409':
          description: "Address or the amount is invalid or if there is no path to the target, or if the identifier is already in use for a different payment."
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'  
        '500':
          description: "Internal Raiden node error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  schemas: 
    Address:
      type: object
      properties:
        our_address: 
          type: string
          example: "0x2a65Aca4D5fC5B5C859090a6c34d164135398226"
      required: 
        - our_address
    TokenNetworkAddress:
      type: object
      properties:
        token_network_address: 
          type: string
          example: "0xC4F8393fb7971E8B299bC1b302F85BfFB3a1275a"
          description: The deployed token networks address.
      required:
        - token_network_address
    Payment:
      type: object
      properties:
        amount:
          type: number
          description: Amount to be sent to the target
        identifier:
          type: number
          description: Identifier of the payment
      required: 
        - amount
    PaymentReceipt:
      type: object
      properties:
        initiator_address:
          type: string
          example: '0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8'
        target_address:
          type: string
          example: '0x61C808D82A3Ac53231750daDc13c777b59310bD9'
        token_address:
          type: string
          example: '0x2a65Aca4D5fC5B5C859090a6c34d164135398226'
        amount:
          type: number
          example: 200
        identifier:
          type: number
          example: 42
        secret:
          type: string
          example: "0x98af0f136712bc9bf89de637b2c4816e6a0dc4c8b92e7ced448fd5806ea64502"
        secret_hash:
          type: string
          example: "0x028b9cf7aef01c94ab85eb26915dc24cd47dba955317f5a1fb02f2ba6014e93b"
      required: 
        - initiator_address
        - target_address
        - token_address
        - amount
        - identifier
        - secret
        - secret_hash
    PaymentEvent:
      type: object
      properties:
        event: 
          type: string
          enum: ['EventPaymentReceivedSuccess', 'EventPaymentSentSuccess', 'EventPaymentSentFailed']
        amount:
          type: number
          example: 5
        initiator:
          type: string
          example: "0x82641569b2062B545431cF6D7F0A418582865ba7"
        identifier:
          type: integer
          example: 1
        log_time:
          type: string
          example: "2018-10-30T07:03:52.193"
      required:
        - event
        - amount
        - initiator
        - identifier
        - log_time
    TotalWithdraw:
      type: integer
      example: 5000000
      description: "Amount of the `token_address` token we have withdrawn into the contract for this channel."
    TotalDeposit:
      type: integer
      description: "Amount of the `token_address` token we have deposited into the contract for this channel."
      example: 35000000
    IncreaseWithdraw:
      type: integer
      description: "The increased total withdrawal"
      example: 35000000
    IncreaseDeposit:
      type: integer
      example: 5000000
      description: "The increased total deposit"
    Connection:
      type: object
      properties:
        funds: 
          type: integer
        sum_deposits:
          type: integer
        channels:
          type: integer
      required: 
        - funds
        - sum_deposits
        - channels
    ChannelAllocation:
      type: object
      properties:
        funds: 
          type: integer
          description: "Amount of funding you want to put into the network."
          example: 1337
        initial_channel_target:
          type: integer
          description: "Number of channels to open proactively."
          default: 3
          example: 3
        joinable_funds_target:
          type: number
          description: "Fraction of funds that will be used to join channels opened by other participants."
          default: 0.4
          example: 0.4
      required: 
        - funds
    ChannelPartial:
      type: object
      properties:
        partner_address:
          type: string
          description: "[EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded address of the partner with whom we have opened a channel"
          example: "0x61C808D82A3Ac53231750daDc13c777b59310bD9"
        token_address:
          type: string
          description: "[EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded address of the token we are trading in the channel"
          example: "0xEA674fdDe714fd979de3EdF0F56AA9716B898ec8"
        total_deposit:
          $ref: '#/components/schemas/TotalDeposit'
        settle_timeout:
          type: integer
          description: "The number of blocks that are required to be mined from the time that close() is called until the channel can be settled with a call to settle()"
          example: 500
      required: 
        - partner_address
        - token_address
        - total_deposit
        - settle_timeout
    ChannelState:
      type: string
      description: "Current state of the channel"
      enum: ['opened', 'closed', 'settled']
      example: 'opened'
    Channel:
      allOf: 
        - $ref: '#/components/schemas/ChannelPartial'
        - type: object
          properties:
            channel_identifier:
              type: integer
              description: Identifier of the channel
              example: 21
            token_network_identifier:
              type: string
              description: "[EIP55](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-55.md)-encoded address of the token network the channel is part of"
              example: "0x2a65Aca4D5fC5B5C859090a6c34d164135398226"
            balance:
              type: integer
              description: "Amount of the `token_address` token we have available for payments."
              example: 25000000
            total_withdraw:
              $ref: '#/components/schemas/TotalWithdraw'
            state:
              $ref: '#/components/schemas/ChannelState'
            reveal_timeout:
              type: integer
              description: "The maximum number of blocks allowed between the setting of a hashlock and the revealing of the related secret."
              example: 40
          required: 
            - channel_identifier
            - token_network_identifier
            - balance
            - state
            - reveal_timeout
    Partner:
      type: object
      properties:
        partner_address:
          type: string
          description: The partner we have a channel with
          example: "0x2a65aca4d5fc5b5c859090a6c34d164135398226"
        channel:
          type: string
          description: A link to the channel resource
          example: "/api/<version>/channels/0x61C808D82A3Ac53231750daDc13c777b59310bD90x2a65aca4d5fc5b5c859090a6c34d164135398226"
      required: 
        - partner_address
        - channel
    PendingTransfer:
      type: object
      properties:
        channel_identifier: 
          type: string
          example: "255"
        initiator:
          type: string
          example: "0x5E1a3601538f94c9e6D2B40F7589030ac5885FE7"
        locked_amount:
          type: string
          example: "119"
        payment_identifier:
          type: string
          example: "1"
        role:
          type: string
          enum: ['initiator', 'mediator', 'target']
        target:
          type: string
          example: "0x00AF5cBfc8dC76cd599aF623E60F763228906F3E"
        token_address:
          type: string
          example: "0xd0A1E359811322d97991E03f863a0C30C2cF029C"
        token_network_identifier:
          type: string
          example: "0x111157460c0F41EfD9107239B7864c062aA8B978"
        transferred_amount:
          type: string
          example: "331"
      required: 
        - channel_identifier
        - initiator
        - locked_amount
        - payment_identifier
        - role
        - target
        - token_address
        - token_network_identifier
        - transferred_amount
    Errors:
      type: object
      properties:
        errors: 
          type: array
          items:
            type: string
      required: 
        - errors