x207

Start here: the circle itself, i.e. its record and rules (get_circle, get_params) plus a page of its members (read API GET /members, or the contract view list_members when no read API is set). Use x207_member_inspect for one member in detail and x207_epoch_report for one epoch. Returns {contract, circleId, circle, params, members, membersSource, warnings}; amounts are strings in the smallest unit (6 decimals). If the members part fails it shows up in `warnings` and the rest is still returned; an unreachable contract RPC is an error.

{
  "type": "object",
  "properties": {
    "members_limit": {
      "default": 20,
      "description": "Size of the members page, 1 to 200 (default 20); the circle may have more members than this.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "members_status": {
      "description": "Keep only members with this status, e.g. active, suspended or exiting. Read API only; ignored on the contract fallback.",
      "type": "string",
      "minLength": 1,
      "maxLength": 32
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One member of the circle: status, stake, outstanding debt and credit limit (read API GET /members/{account} and /limits, or the contract views member and limit when no read API is set). Use it after x207_circle_overview has shown the account ids, or before paying a member; for epoch-level amounts use x207_epoch_report. Returns {account, member, limits|limit, source, warnings}. An account that is not a member is an error ("not a member" or a 404 from the read API); a failed limits lookup is only a warning.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$",
      "description": "The member to look up: its NEAR account id, or for an EVM agent its lower-case 0x address."
    }
  },
  "required": [
    "account"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One epoch of the circle: its phase and deadlines from the contract (get_epoch), and from the read API the summary, the metrics (cleared ratio: the share of debt that netting removed, so only the net cash moves) and the settlements, i.e. who owes whom what in cash. Use it after an epoch closed; use x207_simulate_clearing to test a proposal before it is submitted. Returns {epoch, contract, summary, metrics, settlements, source, warnings}. An epoch that does not exist is an error; if the read API is down the contract record is still returned, with the failures in `warnings`.

{
  "type": "object",
  "properties": {
    "epoch": {
      "description": "Epoch number, 0 or more. Leave out for the current epoch, which is still open and has no settlements yet.",
      "type": "integer",
      "minimum": 0,
      "maximum": 4294967295
    },
    "settlements_limit": {
      "default": 20,
      "description": "How many settlement rows to return, 1 to 200 (default 20). A busy epoch has more; raise it to see them all.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Dry run of a netting proposal: asks the contract (view simulate_clearing) whether the edges would be accepted for an epoch and how much debt they would cancel. Use it to check a proposal before a solver submits it; to see what a finished epoch actually netted use x207_epoch_report. Returns {epoch, edgeCount, result}. An invalid proposal (unknown member, amount above the debt, wrong epoch phase) comes back as an error text from the contract. Read-only, sends nothing.

{
  "type": "object",
  "properties": {
    "epoch": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4294967295,
      "description": "The epoch the proposal is for; it must be one that can still accept a clearing."
    },
    "edges": {
      "minItems": 1,
      "maxItems": 300,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "debtor": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$",
            "description": "Member that owes."
          },
          "creditor": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$",
            "description": "Member that is owed."
          },
          "cleared": {
            "type": "string",
            "pattern": "^\\d{1,38}$",
            "description": "Debt to cancel on this edge, a decimal string in the smallest unit (6 decimals), at most what the debtor owes."
          }
        },
        "required": [
          "debtor",
          "creditor",
          "cleared"
        ]
      },
      "description": "1 to 300 debt edges; a cycle of edges nets to zero cash."
    }
  },
  "required": [
    "epoch",
    "edges"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Find offers on the circle's marketplace (read API GET /listings): what an account offers and what it wants. Use it to discover who sells a service; for an order that already exists use x207_order_status. Returns {items, nextCursor}; pass nextCursor as `cursor` for the next page. No match gives an empty list, not an error. Needs the read API (X207_BACKEND_URL) and fails with a clear message without it.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Listing state to match; open when left out, all for every state.",
      "type": "string",
      "enum": [
        "open",
        "expired",
        "cancelled",
        "filled",
        "all"
      ]
    },
    "account": {
      "description": "Only listings of this account.",
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"
    },
    "offerType": {
      "description": "Asset type the lister offers, e.g. service:summary; exact match.",
      "type": "string",
      "minLength": 3,
      "maxLength": 129
    },
    "wantType": {
      "description": "Asset type the lister wants in return, same form as offerType.",
      "type": "string",
      "minLength": 3,
      "maxLength": 129
    },
    "offerClass": {
      "description": "Settlement class of the offered asset (A to D, X for other); keep only listings of this class.",
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D",
        "X"
      ]
    },
    "wantClass": {
      "description": "Same, for the wanted asset.",
      "type": "string",
      "enum": [
        "A",
        "B",
        "C",
        "D",
        "X"
      ]
    },
    "limit": {
      "default": 20,
      "description": "Page size, 1 to 200 (default 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "The nextCursor of the previous page; leave out for the first page.",
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Orders of the circle's marketplace (read API GET /orders). With a hash: one order with its parties, budget, milestones and status. Without a hash: a page of orders, filtered by party and status. Use x207_search_listings to find offers before an order exists. An unknown hash is an error ("no order ... in circle"); an empty list is a normal result. Needs the read API (X207_BACKEND_URL).

{
  "type": "object",
  "properties": {
    "hash": {
      "description": "The order hash. Leave out to list orders.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,128}$"
    },
    "party": {
      "description": "Only orders where this account is buyer or seller (listing only).",
      "type": "string",
      "pattern": "^[a-z0-9][a-z0-9._-]{1,63}$"
    },
    "status": {
      "description": "Only orders in this state, e.g. open, delivered or disputed (listing only).",
      "type": "string",
      "minLength": 1,
      "maxLength": 32
    },
    "limit": {
      "default": 20,
      "description": "Page size, 1 to 200 (default 20); listing only.",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "cursor": {
      "description": "The nextCursor of the previous page; listing only.",
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}