DocsThe data protocol

price/v1

packages/core/schema/price.schema.json

On this page

What Petals charges for its agent's work (coordinator/pricing-protocol.md; Elco, 10 Nov: "We have a set of fees * multiplied * by a user defined 'tip' rate added protocol defined rate - just so we can either be free, or charge and some users can choose to 'pay more to support' - this is optional switches for now"). A charge is NEAR AI's own bill for the call, plus the fees that are switched on times the person's tip, plus the protocol's rate of the bill. Every switch off is Petals at cost. Each charge names the hash of the price it used.

Fields

Field	Type or allowed values	Presence in its parent	Description
`petal`	"price/v1"	Required
`form`	"bill + fees * tip + protocol * bill"	Required	how the parts add up: the bill, plus fees times the tip, plus the protocol's percent of the bill
`fees`	object	Required
`fees.usage`	object	Required	(A) a percent of each call's bill
`fees.usage.on`	boolean	Required
`fees.usage.percent`	number	Required
`fees.top_up`	object	Required	(B) a percent of each top-up, kept by Petals when it lands
`fees.top_up.on`	boolean	Required
`fees.top_up.percent`	number	Required
`fees.per_turn`	object	Required	(C) dollars for each turn of Petals' agent
`fees.per_turn.on`	boolean	Required
`fees.per_turn.usd`	number	Required
`fees.per_tool`	object	Required	(D) dollars for each use of a tool Petals runs, by the tool's name
`fees.per_tool.on`	boolean	Required
`fees.per_tool.usd`	object	Required
`fees.per_tool.usd.*`	number	Optional
`fees.free`	object	Required	(E) dollars of NEAR AI's bill a person runs before any of Petals' charges
`fees.free.on`	boolean	Required
`fees.free.usd`	number	Required
`protocol`	object	Required	the protocol's own rate: a percent of each call's bill, not multiplied by the tip
`protocol.on`	boolean	Required
`protocol.percent`	number	Required
`tip`	object	Required	the person's multiplier on the fees: theirs to set between min and max, default unless they do
`tip.default`	number	Required
`tip.min`	number	Required
`tip.max`	number	Required

Examples

price.v1.json

Fixture source

{
  "petal": "price/v1",
  "form": "bill + fees * tip + protocol * bill",
  "fees": {
    "usage": {
      "on": false,
      "percent": 0
    },
    "top_up": {
      "on": false,
      "percent": 0
    },
    "per_turn": {
      "on": false,
      "usd": 0
    },
    "per_tool": {
      "on": false,
      "usd": {}
    },
    "free": {
      "on": false,
      "usd": 0
    }
  },
  "protocol": {
    "on": false,
    "percent": 0
  },
  "tip": {
    "default": 1,
    "min": 0,
    "max": 10
  }
}

Full schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:petal:schema:price:v1",
  "title": "Petal price v1",
  "description": "What Petals charges for its agent's work (coordinator/pricing-protocol.md; Elco, 10 Nov: \"We have a set of fees * multiplied * by a user defined 'tip' rate *added* protocol defined rate - just so we can either be free, or charge and some users can choose to 'pay more to support' - this is optional switches for now\"). A charge is NEAR AI's own bill for the call, plus the fees that are switched on times the person's tip, plus the protocol's rate of the bill. Every switch off is Petals at cost. Each charge names the hash of the price it used.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "petal",
    "form",
    "fees",
    "protocol",
    "tip"
  ],
  "properties": {
    "petal": {
      "const": "price/v1"
    },
    "form": {
      "description": "how the parts add up: the bill, plus fees times the tip, plus the protocol's percent of the bill",
      "const": "bill + fees * tip + protocol * bill"
    },
    "fees": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "usage",
        "top_up",
        "per_turn",
        "per_tool",
        "free"
      ],
      "properties": {
        "usage": {
          "description": "(A) a percent of each call's bill",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "on",
            "percent"
          ],
          "properties": {
            "on": {
              "type": "boolean"
            },
            "percent": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            }
          }
        },
        "top_up": {
          "description": "(B) a percent of each top-up, kept by Petals when it lands",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "on",
            "percent"
          ],
          "properties": {
            "on": {
              "type": "boolean"
            },
            "percent": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            }
          }
        },
        "per_turn": {
          "description": "(C) dollars for each turn of Petals' agent",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "on",
            "usd"
          ],
          "properties": {
            "on": {
              "type": "boolean"
            },
            "usd": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "per_tool": {
          "description": "(D) dollars for each use of a tool Petals runs, by the tool's name",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "on",
            "usd"
          ],
          "properties": {
            "on": {
              "type": "boolean"
            },
            "usd": {
              "type": "object",
              "propertyNames": {
                "pattern": "^[a-z][a-z0-9_]{0,40}$"
              },
              "additionalProperties": {
                "type": "number",
                "minimum": 0
              }
            }
          }
        },
        "free": {
          "description": "(E) dollars of NEAR AI's bill a person runs before any of Petals' charges",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "on",
            "usd"
          ],
          "properties": {
            "on": {
              "type": "boolean"
            },
            "usd": {
              "type": "number",
              "minimum": 0
            }
          }
        }
      }
    },
    "protocol": {
      "description": "the protocol's own rate: a percent of each call's bill, not multiplied by the tip",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "on",
        "percent"
      ],
      "properties": {
        "on": {
          "type": "boolean"
        },
        "percent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        }
      }
    },
    "tip": {
      "description": "the person's multiplier on the fees: theirs to set between min and max, default unless they do",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "default",
        "min",
        "max"
      ],
      "properties": {
        "default": {
          "type": "number",
          "minimum": 0
        },
        "min": {
          "type": "number",
          "minimum": 0
        },
        "max": {
          "type": "number",
          "minimum": 0
        }
      }
    }
  }
}