{ "openrpc": "1.3.2", "info": { "title": "Circles RPC API", "version": "1.0.0", "description": "JSON-RPC 2.0 API for the Circles protocol on Gnosis Chain.\n\n## Overview\nThis API provides access to all indexed Circles protocol data: balances, avatars, profiles, trust relations, events, groups, invitations, and transitive transfer path computation.\n\n## Transport\nAll methods use JSON-RPC 2.0 over HTTP POST. Send requests to the root endpoint with \u0060Content-Type: application/json\u0060.\n\n\u0060\u0060\u0060json\n{\u0022jsonrpc\u0022: \u00222.0\u0022, \u0022id\u0022: 1, \u0022method\u0022: \u0022circles_getTotalBalance\u0022, \u0022params\u0022: [\u00220xde374ece6fa50e781e81aac78e811b33d16912c7\u0022, true]}\n\u0060\u0060\u0060\n\n## Pagination\nMethods returning large result sets use cursor-based pagination. The response includes \u0060hasMore\u0060 (boolean) and \u0060nextCursor\u0060 (opaque string). Pass \u0060nextCursor\u0060 as the last parameter to get the next page.\n\n## WebSocket Subscriptions\nConnect via WebSocket to \u0060/ws/subscribe\u0060 and send \u0060{\u0022jsonrpc\u0022: \u00222.0\u0022, \u0022method\u0022: \u0022circles_subscribe\u0022, \u0022params\u0022: [\u0022circles\u0022, {\u0022address\u0022: \u00220x...\u0022}]}\u0060 to receive real-time event notifications.\n\n## Ethereum RPC Proxy\nStandard Ethereum methods (eth_*, net_*, web3_*) are proxied to the underlying Nethermind node.\n\n## Related APIs\n- **Pathfinder REST API**: \u0060/pathfinder/scalar/v1\u0060 \u2014 direct access to path computation\n- **Authentication**: \u0060/auth/docs\u0060 \u2014 SIWE authentication and passkey management\n- **All docs**: \u0060/docs\u0060 \u2014 unified documentation portal" }, "methods": [ { "name": "circles_getTotalBalance", "summary": "Get total CRC balance for an address (V1)", "description": "Returns the aggregated V1 Circles balance for an address. The balance can be returned in raw CRC wei or converted to TimeCircles format (which accounts for demurrage/inflation). Use \u0060circlesV2_getTotalBalance\u0060 for V2 balances.\n\n**Common use case**: Display a user\u0027s total balance in a wallet UI. Call with \u0060asTimeCircles: true\u0060 (default) for human-readable values.", "params": [ { "name": "address", "required": true, "description": "The Ethereum address to query the balance for. Must be a registered Circles V1 avatar.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "asTimeCircles", "required": false, "description": "When true (default), converts the balance to TimeCircles format which accounts for CRC inflation. When false, returns the raw CRC wei balance. TimeCircles is the human-readable format used in the Circles UI.", "schema": { "type": "boolean" } } ], "result": { "name": "circles_getTotalBalanceResult", "schema": { "$ref": "#/components/schemas/TotalBalanceResponse" } }, "tags": [ { "name": "Balances" } ], "examples": [ { "name": "Get V1 balance in TimeCircles", "description": "Query a user\u0027s total V1 CRC balance, returned in TimeCircles format", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "asTimeCircles", "value": true } ], "result": { "name": "TotalBalanceResponse", "value": { "totalBalance": "142.5678", "version": 1, "asTimeCircles": true } } } ] }, { "name": "circlesV2_getTotalBalance", "summary": "Get total CRC balance for an address (V2)", "description": "Returns the aggregated V2 Circles balance for an address. V2 uses ERC-1155 tokens with demurrage (value decreases ~7%/year). TimeCircles conversion adjusts for this decay.\n\n**Common use case**: Display V2 balance. Pair with \u0060circles_getTokenBalances\u0060 to see individual token breakdowns.\n\n**Note**: V2 balances include both personal tokens and group tokens held by the address.", "params": [ { "name": "address", "required": true, "description": "The Ethereum address to query the V2 balance for. Must be a registered Circles V2 avatar.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "asTimeCircles", "required": false, "description": "When true (default), converts the balance to TimeCircles format which accounts for V2 demurrage (~7%/year decay). When false, returns the raw CRC wei balance with demurrage already applied.", "schema": { "type": "boolean" } } ], "result": { "name": "circlesV2_getTotalBalanceResult", "schema": { "$ref": "#/components/schemas/TotalBalanceResponse" } }, "tags": [ { "name": "Balances" } ], "examples": [ { "name": "Get V2 balance in raw CRC", "description": "Query a user\u0027s total V2 CRC balance in raw wei", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "asTimeCircles", "value": false } ], "result": { "name": "TotalBalanceResponse", "value": { "totalBalance": "142567800000000000000", "version": 2, "asTimeCircles": false } } } ] }, { "name": "circles_getTokenBalances", "summary": "Get all token balances for an address", "description": "Returns every individual Circles token held by the address, including V1 CRC tokens, V2 personal tokens, V2 group tokens, and ERC-20 wrapped tokens. Each entry includes the token address, owner, type, version, balance amount, and whether it\u0027s wrapped/inflationary.\n\n**Common use case**: Build a token portfolio view. Use alongside \u0060circles_getTokenInfo\u0060 to resolve token metadata.\n\n**Tip**: To get just the total, use \u0060circles_getTotalBalance\u0060 or \u0060circlesV2_getTotalBalance\u0060 instead.", "params": [ { "name": "address", "required": true, "description": "The Ethereum address to query token balances for. Returns all V1 and V2 Circles tokens held by this address, including personal tokens, group tokens, and ERC-20 wrappers.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getTokenBalancesResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CirclesTokenBalance" } } }, "tags": [ { "name": "Balances" } ], "examples": [ { "name": "List all token balances", "description": "Get every Circles token held by an address", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getTokenInfo", "summary": "Get information about a specific token", "description": "Returns metadata for a single token: owner address, type (personal/group), version (1/2), whether it\u0027s an ERC-20 wrapper, inflationary, or a group token.\n\n**Common use case**: Resolve a token address encountered in a transfer event to understand what kind of token it is.\n\n**Returns null** if the token address is not known to the indexer.", "params": [ { "name": "tokenAddress", "required": true, "description": "The token contract address (V1 CRC token) or token ID (V2 ERC-1155). Returns metadata about the token including owner, type, version, and flags.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getTokenInfoResult", "schema": { "$ref": "#/components/schemas/TokenInfo" } }, "tags": [ { "name": "Tokens" } ], "examples": [ { "name": "Look up a token", "description": "Get metadata for a specific token address", "params": [ { "name": "tokenAddress", "value": "0xc5d024cb3218c4bfb3cdf1178e04c87742123708" } ] } ] }, { "name": "circles_getTokenInfoBatch", "summary": "Get information about multiple tokens", "description": "Batch version of \u0060circles_getTokenInfo\u0060. Returns an array with the same length as the input; positions with unknown tokens contain null.\n\n**Common use case**: After fetching \u0060circles_getTokenBalances\u0060, resolve all token addresses in a single call instead of N individual calls.", "params": [ { "name": "tokenAddresses", "required": true, "description": "Array of token addresses to look up. Returns an array of the same length with null entries for unknown tokens. Max recommended batch size: 100.", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_getTokenInfoBatchResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TokenInfo" } } }, "tags": [ { "name": "Tokens" } ], "examples": [ { "name": "Batch token lookup", "description": "Resolve multiple token addresses at once", "params": [ { "name": "tokenAddresses", "value": [ "0xc5d024cb3218c4bfb3cdf1178e04c87742123708", "0xde374ece6fa50e781e81aac78e811b33d16912c7" ] } ] } ] }, { "name": "circles_getAvatarInfo", "summary": "Get avatar information for an address", "description": "Returns registration info for a Circles avatar: version, type (Human/Organization/Group), associated token ID, V1 token (if migrated), IPFS profile CID, name, and symbol.\n\n**Common use case**: Check if an address is registered in Circles and what type of avatar it is. Essential before initiating trust or transfer operations.\n\n**Throws** if the address is not registered as a Circles avatar.", "params": [ { "name": "address", "required": true, "description": "The address to look up. Returns registration info including avatar type (Human/Organization/Group), V1/V2 status, token ID, IPFS profile CID, and on-chain name/symbol.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getAvatarInfoResult", "schema": { "$ref": "#/components/schemas/AvatarInfo" } }, "tags": [ { "name": "Avatars" } ], "examples": [ { "name": "Check if an address is registered", "description": "Look up avatar registration info \u2014 throws if not registered", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ], "result": { "name": "AvatarInfo", "value": { "version": 2, "type": "CrcV2_RegisterHuman", "avatar": "0xde374ece6fa50e781e81aac78e811b33d16912c7", "tokenId": "0xc5d024cb3218c4bfb3cdf1178e04c87742123708", "hasV1": true, "v1Token": "0xc5d024cb3218c4bfb3cdf1178e04c87742123708", "cidV0Digest": "0x1234...", "cidV0": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG", "isHuman": true, "name": "Alice", "symbol": "ALICE" } } } ] }, { "name": "circles_getAvatarInfoBatch", "summary": "Get avatar information for multiple addresses", "description": "Batch version of \u0060circles_getAvatarInfo\u0060. Efficient for resolving multiple avatars in a contact list or trust network view.\n\n**Common use case**: Given a list of trusted addresses, resolve all their avatar info in one call for rendering a contacts UI.", "params": [ { "name": "addresses", "required": true, "description": "Array of addresses to look up. Returns avatar info for each; throws for unregistered addresses. Max recommended batch size: 100.", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_getAvatarInfoBatchResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AvatarInfo" } } }, "tags": [ { "name": "Avatars" } ], "examples": [ { "name": "Batch avatar lookup", "description": "Get avatar info for a contact list", "params": [ { "name": "addresses", "value": [ "0xde374ece6fa50e781e81aac78e811b33d16912c7", "0x42cEDde51198D1773590311E2A340DC06B24cB37" ] } ] } ] }, { "name": "circles_getProfileCid", "summary": "Get IPFS CID for an avatar\u0027s profile", "description": "Returns the IPFS Content Identifier (CIDv0) pointing to the avatar\u0027s profile JSON. The profile is stored on IPFS and contains name, description, image URL, etc.\n\n**Common use case**: Check if an avatar has a profile set, or get the CID for direct IPFS retrieval. Use \u0060circles_getProfileByAddress\u0060 instead if you want the full profile content.", "params": [ { "name": "address", "required": true, "description": "The avatar address to get the profile CID for. The CID points to an IPFS document containing the avatar\u0027s profile (name, description, image URL).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getProfileCidResult", "schema": { "$ref": "#/components/schemas/ProfileCidResponse" } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Get IPFS CID for a profile", "description": "Get the IPFS content identifier for an avatar\u0027s profile", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getProfileCidBatch", "summary": "Get IPFS CIDs for multiple avatars", "description": "Batch version of \u0060circles_getProfileCid\u0060. Returns a map of address \u2192 CID (null if no profile).\n\n**Common use case**: Pre-fetch CIDs for a list of avatars before loading profiles.", "params": [ { "name": "addresses", "required": true, "description": "Array of avatar addresses. Returns a map of address \u2192 CIDv0 string (null if no profile set).", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_getProfileCidBatchResult", "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Batch CID lookup", "description": "Get IPFS CIDs for multiple avatars at once", "params": [ { "name": "addresses", "value": [ "0xde374ece6fa50e781e81aac78e811b33d16912c7", "0x42cEDde51198D1773590311E2A340DC06B24cB37" ] } ] } ] }, { "name": "circles_getProfileByCid", "summary": "Get profile content by IPFS CID", "description": "Fetches and returns the profile JSON stored at the given IPFS CID. Results are cached server-side for performance.\n\n**Common use case**: Load a profile after obtaining its CID from \u0060circles_getProfileCid\u0060 or \u0060circles_getAvatarInfo\u0060.", "params": [ { "name": "cid", "required": true, "description": "IPFS Content Identifier (CIDv0 format, e.g., \u0027QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG\u0027). The server caches IPFS content for performance.", "schema": { "type": "string" } } ], "result": { "name": "circles_getProfileByCidResult", "schema": { "type": "object", "description": "Profile JSON object from IPFS. Schema varies by profile version \u2014 typically contains name, description, imageUrl, and other user-defined fields." } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Fetch profile by IPFS CID", "description": "Load profile JSON from IPFS via the server-side cache", "params": [ { "name": "cid", "value": "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG" } ] } ] }, { "name": "circles_getProfileByCidBatch", "summary": "Get multiple profile contents by CIDs", "description": "Batch version of \u0060circles_getProfileByCid\u0060. Returns array in same order as input CIDs.", "params": [ { "name": "cids", "required": true, "description": "Array of IPFS CIDs to fetch. Returns profile JSON objects in the same order, with null for CIDs that couldn\u0027t be resolved.", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_getProfileByCidBatchResult", "schema": { "type": "array", "items": { "type": "object", "description": "Arbitrary JSON value", "nullable": true } } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Batch profile fetch", "description": "Load multiple profiles by their IPFS CIDs", "params": [ { "name": "cids", "value": [ "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG", "QmPbxeGcXhYQoAkwH5LRZSxvAXKTDJoNTJHVLHXHFkN3aR" ] } ] } ] }, { "name": "circles_getProfileByAddress", "summary": "Get profile by avatar address", "description": "Convenience method that combines CID lookup \u002B IPFS fetch in one call. Returns the full profile JSON enriched with avatar type and short name from V2 registrations.\n\n**Common use case**: Display a user profile card \u2014 this single call replaces \u0060circles_getProfileCid\u0060 \u002B \u0060circles_getProfileByCid\u0060 \u002B \u0060circles_getAvatarInfo\u0060.\n\n**Tip**: For rendering multiple profiles, use the batch variant or \u0060circles_getProfileView\u0060 (which also includes balances and trust stats).", "params": [ { "name": "address", "required": true, "description": "Avatar address. Combines CID lookup \u002B IPFS fetch \u002B avatar enrichment in one call. The returned profile JSON includes injected \u0027avatarType\u0027 and \u0027name\u0027 fields from V2 registration data.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getProfileByAddressResult", "schema": { "type": "object", "description": "Profile JSON from IPFS, enriched with avatar type and short name from V2 registration. Schema varies by profile version." } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Get enriched profile", "description": "Fetch a profile with avatar type and name injected", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getProfileByAddressBatch", "summary": "Get profiles for multiple addresses", "description": "Batch version of \u0060circles_getProfileByAddress\u0060. Each profile is enriched with avatar type and short name.\n\n**Common use case**: Render a list of user cards in a search result or trust list.", "params": [ { "name": "addresses", "required": true, "description": "Array of avatar addresses. Each profile is enriched with avatarType and name. More efficient than N individual calls. Max recommended batch size: 50.", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_getProfileByAddressBatchResult", "schema": { "type": "array", "items": { "type": "object", "description": "Arbitrary JSON value", "nullable": true } } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Batch enriched profiles", "description": "Fetch profiles for a list of addresses with avatar enrichment", "params": [ { "name": "addresses", "value": [ "0xde374ece6fa50e781e81aac78e811b33d16912c7", "0x42cEDde51198D1773590311E2A340DC06B24cB37" ] } ] } ] }, { "name": "circles_searchProfiles", "summary": "Full-text search across profiles", "description": "Searches avatar profiles by name and description text. Supports up to 3 search tokens (each must be \u003E 1 character). Can filter by avatar type.\n\n**Common use case**: User search bar \u2014 type a name, get matching profiles.\n\n**Tip**: For searching by address prefix OR name, use \u0060circles_searchProfileByAddressOrName\u0060 which auto-detects the query type.", "params": [ { "name": "text", "required": true, "description": "Search query text. Split into tokens by whitespace; each token must be \u003E 1 character; max 3 tokens. Searches across profile name and description fields using full-text search.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "description": "Maximum number of results to return. Default: 20, maximum: 100. Use with offset for pagination.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "description": "Number of results to skip. Use with limit for offset-based pagination (e.g., offset=20, limit=20 for page 2).", "schema": { "type": "integer" } }, { "name": "types", "required": false, "description": "Filter results by avatar type. Valid values: \u0027CrcV2_RegisterHuman\u0027, \u0027CrcV2_RegisterGroup\u0027, \u0027CrcV2_RegisterOrganization\u0027. Omit to search all types.", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_searchProfilesResult", "schema": { "$ref": "#/components/schemas/ProfileSearchResult" } }, "tags": [ { "name": "Profiles" } ], "examples": [ { "name": "Search by name", "description": "Find profiles matching \u0027alice\u0027 with max 10 results", "params": [ { "name": "text", "value": "alice" }, { "name": "limit", "value": 10 }, { "name": "offset", "value": 0 } ] }, { "name": "Search groups only", "description": "Find group profiles matching \u0027community\u0027", "params": [ { "name": "text", "value": "community" }, { "name": "limit", "value": 20 }, { "name": "offset", "value": 0 }, { "name": "types", "value": [ "CrcV2_RegisterGroup" ] } ] } ] }, { "name": "circles_getTrustRelations", "summary": "Get trust relations for an address", "description": "Returns two arrays: \u0060trusts\u0060 (addresses this avatar trusts) and \u0060trustedBy\u0060 (addresses that trust this avatar), each with the trust limit.\n\n**Common use case**: Display a user\u0027s trust network. The trust limit indicates the percentage of tokens accepted (100 = full trust, 0 = no trust).\n\n**Note**: Currently returns V1 trust relations. For V2, use \u0060circles_getAggregatedTrustRelations\u0060.", "params": [ { "name": "address", "required": true, "description": "The avatar address to query trust relations for. Returns bidirectional trust data: who this avatar trusts (outgoing) and who trusts this avatar (incoming).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getTrustRelationsResult", "schema": { "$ref": "#/components/schemas/TrustRelationsResponse" } }, "tags": [ { "name": "Trust" } ], "examples": [ { "name": "Get trust network for an address", "description": "View who this address trusts and who trusts it", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getCommonTrust", "summary": "Find common trust connections between two addresses", "description": "Finds addresses that both users trust (or that trust both users), forming potential transfer intermediaries. For V2 humans, uses directional trust paths (outgoing \u2192 incoming). For V2 groups and V1, uses shared outgoing trusts.\n\n**Common use case**: Before a transfer, check if there\u0027s a common trust path. Also useful for \u0027mutual friends\u0027 UI features.\n\n**Tip**: Use together with \u0060circlesV2_findPath\u0060 \u2014 if no common trust exists, a path likely won\u0027t be found either.", "params": [ { "name": "address1", "required": true, "description": "First address in the pair. For V2 humans, this is the \u0027outgoing trust\u0027 side (address1\u0027s trusts \u2192 common \u2192 address2\u0027s trustedBy).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "address2", "required": true, "description": "Second address in the pair. For V2 humans, this is the \u0027incoming trust\u0027 side.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "version", "required": false, "description": "Filter by protocol version: 1 = V1 only, 2 = V2 only, null/omit = both versions. V1 and V2 trust graphs are independent.", "schema": { "type": "integer" } } ], "result": { "name": "circles_getCommonTrustResult", "schema": { "$ref": "#/components/schemas/CommonTrustResponse" } }, "tags": [ { "name": "Trust" } ], "examples": [ { "name": "Find mutual connections (V2)", "description": "Find addresses trusted by both parties in the V2 network", "params": [ { "name": "address1", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "address2", "value": "0x42cEDde51198D1773590311E2A340DC06B24cB37" }, { "name": "version", "value": 2 } ] } ] }, { "name": "circles_getAggregatedTrustRelations", "summary": "Get trust relations grouped by type", "description": "Returns trust relations categorized as \u0027mutuallyTrusts\u0027, \u0027trusts\u0027, or \u0027trustedBy\u0027, with expiry time and counterpart avatar type (Human/Group/Organization). SDK-compatible format.\n\n**Common use case**: Build a trust list UI with sections for mutual trusts vs one-way trusts. The \u0060expiryTime\u0060 field is relevant for V2 trusts which can expire.\n\n**Tip**: For enriched results with profile data included, use \u0060circles_getAggregatedTrustRelationsEnriched\u0060.", "params": [ { "name": "avatar", "required": true, "description": "Avatar address to query aggregated trust relations for. Returns trust relations grouped by counterpart with relation type (mutuallyTrusts/trusts/trustedBy) and expiry times.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getAggregatedTrustRelationsResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AggregatedTrustRelation" } } }, "tags": [ { "name": "Trust" } ], "examples": [ { "name": "Get categorized trust relations", "description": "Trust relations grouped as mutuallyTrusts/trusts/trustedBy", "params": [ { "name": "avatar", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getNetworkSnapshot", "summary": "Get a snapshot of the full trust network", "description": "Returns the complete trust graph: all avatars, trust edges, and token balances. This is a large response (can be several MB) intended for offline analysis or graph visualization.\n\n**Warning**: This is an expensive call. Use sparingly and cache the result. For individual queries, use specific methods instead.\n\n**Common use case**: Graph visualization, analytics dashboards, or pre-loading data for offline pathfinding.", "params": [], "result": { "name": "circles_getNetworkSnapshotResult", "schema": { "type": "object", "description": "Network state snapshot containing trust graph edges, token balances, and avatar registrations. Internal format \u2014 structure may change between versions." } }, "tags": [ { "name": "Network" } ], "examples": [ { "name": "Full network snapshot", "description": "Download the entire trust network (large response, use sparingly)", "params": [] } ] }, { "name": "circles_findGroups", "summary": "Find groups with optional filters", "description": "Discovers Circles groups with optional filtering by name prefix, symbol prefix, or owner addresses. Returns paginated results.\n\n**Common use case**: Group discovery UI \u2014 browse available groups to join.\n\n**Filters** (combine for AND logic):\n- \u0060nameStartsWith\u0060: Filter by group name prefix\n- \u0060symbolStartsWith\u0060: Filter by token symbol prefix\n- \u0060ownerIn\u0060: Only groups owned by specific addresses", "params": [ { "name": "limit", "required": false, "description": "Maximum number of groups to return. Default: 50.", "schema": { "type": "integer" } }, { "name": "queryParams", "required": false, "description": "Optional filter object with fields: nameStartsWith (string), symbolStartsWith (string), ownerIn (string[] of addresses).", "schema": { "type": "object" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } } ], "result": { "name": "circles_findGroupsResult", "schema": { "$ref": "#/components/schemas/PagedResponse_GroupRow" } }, "tags": [ { "name": "Groups" } ], "examples": [ { "name": "Browse all groups", "description": "List first 50 groups with default sorting", "params": [ { "name": "limit", "value": 50 } ] }, { "name": "Search groups by name prefix", "description": "Find groups whose name starts with \u0027Berlin\u0027", "params": [ { "name": "limit", "value": 20 }, { "name": "queryParams", "value": { "nameStartsWith": "Berlin" } } ] } ] }, { "name": "circles_getGroupMembers", "summary": "Get members of a specific group", "description": "Returns addresses that are members (trusted by) a specific group, with cursor-based pagination.\n\n**Common use case**: Display group member list. Members are avatars that the group trusts, meaning their personal tokens can be used to mint the group token.", "params": [ { "name": "groupAddress", "required": true, "description": "The group address to query members for. Returns all avatars that are members of this group with membership metadata.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "required": false, "description": "Maximum number of members to return. Default: 100, max: 200.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } } ], "result": { "name": "circles_getGroupMembersResult", "schema": { "$ref": "#/components/schemas/PagedResponse_GroupMembershipRow" } }, "tags": [ { "name": "Groups" } ], "examples": [ { "name": "List group members", "description": "Get the first 100 members of a group", "params": [ { "name": "groupAddress", "value": "0x9b1BCe0E51F19B392e3F7a053e37930Bfa1e0B5A" }, { "name": "limit", "value": 100 } ] } ] }, { "name": "circles_getGroupMemberships", "summary": "Get groups an avatar is a member of", "description": "Inverse of \u0060circles_getGroupMembers\u0060 \u2014 returns all groups that trust a given avatar address.\n\n**Common use case**: Show which groups a user belongs to in their profile view.", "params": [ { "name": "memberAddress", "required": true, "description": "Avatar address to query group memberships for. Returns all groups this avatar belongs to (inverse of getGroupMembers).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "required": false, "description": "Maximum number of memberships to return. Default: 50, max: 200.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } } ], "result": { "name": "circles_getGroupMembershipsResult", "schema": { "$ref": "#/components/schemas/PagedResponse_GroupMembershipRow" } }, "tags": [ { "name": "Groups" } ], "examples": [ { "name": "Groups I belong to", "description": "Find all groups that trust this avatar", "params": [ { "name": "memberAddress", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "limit", "value": 50 } ] } ] }, { "name": "circles_getTransactionHistory", "summary": "Get transaction history for an avatar", "description": "Returns Circles transfers involving an avatar (as sender or receiver) with cursor-based pagination. Each entry includes from/to addresses, token, amount in multiple formats (CRC wei, TimeCircles, static), block number, and timestamp.\n\n**Common use case**: Transaction history feed in a wallet.\n\n**Params**:\n- \u0060version\u0060: null = both V1\u002BV2, 1 = V1 only, 2 = V2 only\n- \u0060excludeIntermediary\u0060: When true (default), uses TransferSummary which collapses multi-hop transfers into source\u2192destination pairs, hiding intermediary routing hops.\n\n**Tip**: For transaction history with participant profiles pre-loaded, use \u0060circles_getTransactionHistoryEnriched\u0060.", "params": [ { "name": "avatarAddress", "required": true, "description": "Avatar address to query transaction history for. Returns transfers where this avatar is sender or receiver.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "required": false, "description": "Maximum number of transactions to return. Default: 50, max: 200.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } }, { "name": "version", "required": false, "description": "Filter by protocol version: 1 = V1 only, 2 = V2 only, null = both V1\u002BV2.", "schema": { "type": "integer" } }, { "name": "excludeIntermediary", "required": false, "description": "When true (default), uses TransferSummary which excludes intermediary hop transfers. When false, includes all individual hops.", "schema": { "type": "boolean" } } ], "result": { "name": "circles_getTransactionHistoryResult", "schema": { "$ref": "#/components/schemas/PagedResponse_TransactionHistoryRow" } }, "tags": [ { "name": "Transactions" } ], "examples": [ { "name": "Recent V2 transactions", "description": "Get the 50 most recent V2 transfers for an avatar", "params": [ { "name": "avatarAddress", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "limit", "value": 50 }, { "name": "version", "value": 2 }, { "name": "excludeIntermediary", "value": true } ] } ] }, { "name": "circles_getTransferData", "summary": "Get ERC-1155 transfer calldata for an address", "description": "Returns the raw calldata bytes for ERC-1155 transfers involving an address. Can filter by direction (sent/received) and counterparty.\n\n**Common use case**: Inspecting the low-level transfer data for debugging or advanced analysis.\n\n**Params used together**:\n- \u0060direction\u0060 \u002B \u0060counterparty\u0060: e.g., direction=\u0027sent\u0027, counterparty=\u00270x...\u0027 to see all transfers sent to a specific address\n- \u0060fromBlock\u0060 \u002B \u0060toBlock\u0060: Time-range filtering\n- Use \u0060limit\u0060 \u002B \u0060cursor\u0060 for pagination through large result sets", "params": [ { "name": "address", "required": true, "description": "Primary address to filter transfer data for. Returns ERC-1155 transfer calldata bytes.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "direction", "required": false, "description": "Filter by direction: \u0027sent\u0027 (from=address), \u0027received\u0027 (to=address), or null/omit for both.", "schema": { "type": "string" } }, { "name": "counterparty", "required": false, "description": "If set, additionally filters by this specific counterparty address.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "fromBlock", "required": false, "description": "Start block number (inclusive). Null for no lower bound.", "schema": { "type": "integer" } }, { "name": "toBlock", "required": false, "description": "End block number (inclusive). Null for no upper bound.", "schema": { "type": "integer" } }, { "name": "limit", "required": false, "description": "Maximum results. Default: 50, max: 1000.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } } ], "result": { "name": "circles_getTransferDataResult", "schema": { "$ref": "#/components/schemas/PagedResponse_TransferDataRow" } }, "tags": [ { "name": "Transactions" } ], "examples": [ { "name": "Sent transfers to specific address", "description": "Get transfer calldata for all tokens sent from one address to another", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "direction", "value": "sent" }, { "name": "counterparty", "value": "0x42cEDde51198D1773590311E2A340DC06B24cB37" }, { "name": "limit", "value": 50 } ] } ] }, { "name": "circles_getTokenHolders", "summary": "Get all holders of a specific token", "description": "Returns all addresses holding a specific token with their balances. Supports cursor-based pagination.\n\n**Common use case**: Token distribution analysis, or finding who holds a specific group\u0027s token.\n\n**Tip**: The \u0060tokenAddress\u0060 is the token contract address (V1) or token ID (V2 ERC-1155).", "params": [ { "name": "tokenAddress", "required": true, "description": "Token address to query holders for. Returns all addresses holding this token with their balances.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "required": false, "description": "Maximum number of holders to return. Default: 100, max: 200.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination (account address).", "schema": { "type": "string" } } ], "result": { "name": "circles_getTokenHoldersResult", "schema": { "$ref": "#/components/schemas/PagedResponse_TokenHolderRow" } }, "tags": [ { "name": "Tokens" } ], "examples": [ { "name": "Token distribution", "description": "Get all holders of a specific token", "params": [ { "name": "tokenAddress", "value": "0xc5d024cb3218c4bfb3cdf1178e04c87742123708" }, { "name": "limit", "value": 100 } ] } ] }, { "name": "circlesV2_findPath", "summary": "Find a transitive transfer path through the trust network", "description": "Computes a multi-hop transfer path from source to sink through the Circles trust network. Uses the Pathfinder service (Google OR-Tools max-flow solver) to find the optimal set of token transfers.\n\n**This is the primary method for executing Circles transfers.** The response contains the exact transfer steps to submit on-chain.\n\n**Key parameters**:\n- \u0060source\u0060/\u0060sink\u0060: Sender and receiver addresses\n- \u0060targetFlow\u0060: Amount to transfer in CRC wei (use max uint256 for \u0027send as much as possible\u0027)\n- \u0060fromTokens\u0060/\u0060toTokens\u0060: Restrict which tokens can be used at source/sink\n- \u0060excludedFromTokens\u0060/\u0060excludedToTokens\u0060: Exclude specific tokens\n- \u0060withWrap\u0060: Include ERC-20 wrapper paths\n- \u0060quantizedMode\u0060: Enforce 96 CRC quantization (for invitations)\n- \u0060maxTransfers\u0060: Limit number of transfer steps\n- \u0060simulatedBalances\u0060: Test with hypothetical balances\n- \u0060debugShowIntermediateSteps\u0060: Include all transformation stages in response\n\n**Common use cases**:\n1. **Simple transfer**: Set source, sink, targetFlow\n2. **Maximum possible transfer**: Set targetFlow to max uint256\n3. **Invitation flow**: Set quantizedMode=true, targetFlow = N * 96 CRC\n4. **Debugging**: Set debugShowIntermediateSteps=true to see rawPaths \u2192 collapsed \u2192 routerInserted \u2192 sorted stages", "params": [ { "name": "flowRequest", "required": true, "description": "Path computation request. Contains source (sender), sink (receiver), targetFlow (amount in CRC wei), and optional filters for tokens, wrapping, quantization, simulation, and debugging. See FlowRequest schema for all fields.", "schema": { "$ref": "#/components/schemas/FlowRequest" } } ], "result": { "name": "circlesV2_findPathResult", "schema": { "$ref": "#/components/schemas/MaxFlowResponse" } }, "tags": [ { "name": "Pathfinder" } ], "examples": [ { "name": "Simple transfer", "description": "Find a path to transfer 10 CRC from sender to receiver", "params": [ { "name": "flowRequest", "value": { "source": "0xde374ece6fa50e781e81aac78e811b33d16912c7", "sink": "0x42cEDde51198D1773590311E2A340DC06B24cB37", "targetFlow": "10000000000000000000" } } ] }, { "name": "Maximum possible transfer", "description": "Discover the maximum amount transferable between two addresses", "params": [ { "name": "flowRequest", "value": { "source": "0xde374ece6fa50e781e81aac78e811b33d16912c7", "sink": "0x42cEDde51198D1773590311E2A340DC06B24cB37", "targetFlow": "115792089237316195423570985008687907853269984665640564039457584007913129639935" } } ] }, { "name": "Quantized invitation transfer", "description": "Transfer exactly 2 invitation units (2 x 96 CRC = 192 CRC) with quantization", "params": [ { "name": "flowRequest", "value": { "source": "0xde374ece6fa50e781e81aac78e811b33d16912c7", "sink": "0x42cEDde51198D1773590311E2A340DC06B24cB37", "targetFlow": "192000000000000000000", "quantizedMode": true } } ] }, { "name": "Debug transfer path", "description": "Find a path with all intermediate transformation stages visible", "params": [ { "name": "flowRequest", "value": { "source": "0xde374ece6fa50e781e81aac78e811b33d16912c7", "sink": "0x42cEDde51198D1773590311E2A340DC06B24cB37", "targetFlow": "10000000000000000000", "debugShowIntermediateSteps": true, "maxTransfers": 5 } } ] } ] }, { "name": "circles_events", "summary": "Query indexed blockchain events (flat array, backwards compatible)", "description": "Returns Circles protocol events as a **plain JSON array** for backwards compatibility with existing consumers. Same parameters and filtering as \u0060circles_events_paginated\u0060 but without pagination metadata.\n\n**For paginated results**, use \u0060circles_events_paginated\u0060 which returns \u0060{events, hasMore, nextCursor}\u0060.\n\n**Event types include**: CrcV1_Trust, CrcV1_Transfer, CrcV2_Trust, CrcV2_TransferSingle, CrcV2_TransferBatch, CrcV2_RegisterHuman, CrcV2_RegisterGroup, CrcV2_RegisterOrganization, and many more.", "params": [ { "name": "address", "required": false, "description": "Filter events by this address (as sender, receiver, or involved party). Null = all addresses. Case-insensitive.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "fromBlock", "required": false, "description": "Starting block number (inclusive). Combine with toBlock for time-range queries. Gnosis Chain produces ~1 block per 5 seconds.", "schema": { "type": "integer" } }, { "name": "toBlock", "required": false, "description": "Ending block number (inclusive). Null = up to the latest indexed block.", "schema": { "type": "integer" } }, { "name": "eventTypes", "required": false, "description": "Filter by event types. Examples: [\u0027CrcV2_TransferSingle\u0027,\u0027CrcV2_Trust\u0027], [\u0027CrcV1_Transfer\u0027], [\u0027CrcV2_RegisterHuman\u0027]. Null = all event types. Use circles_tables to discover all event types.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filterPredicates", "required": false, "description": "Advanced filter predicates for SQL-like filtering. Each predicate has Type, FilterType, Column, and Value. IMPORTANT: For \u0027In\u0027/\u0027NotIn\u0027 FilterType, Value MUST be an array (e.g., [\u00220xabc...\u0022]). For scalar operators (Equals, GreaterThan, etc.), Value is a single string or number. See FilterPredicateDto schema.", "schema": { "$ref": "#/components/schemas/FilterPredicateDto" } }, { "name": "sortAscending", "required": false, "description": "Sort order by block number. Default: false (newest first). Set true for chronological order. Note: this is a positional parameter \u2014 you must pass it (or null) to set limit or cursor at later positions.", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "description": "Maximum events to return per page. Default: 100, maximum: 1000. Pass null or omit to use the default of 100.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Opaque cursor from a previous response\u0027s nextCursor field for pagination. Do not construct manually.", "schema": { "type": "string" } } ], "result": { "name": "circles_eventsResult", "schema": { "type": "array", "description": "Flat array of event objects. Each element has blockNumber, transactionHash, logIndex, event (type name), and payload. For paginated results with hasMore/nextCursor, use circles_events_paginated.", "items": { "type": "object" } } }, "tags": [ { "name": "Events" } ], "examples": [ { "name": "Recent transfers for an address", "description": "Get the 50 most recent V2 transfers involving an address", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "eventTypes", "value": [ "CrcV2_TransferSingle" ] }, { "name": "sortAscending", "value": false }, { "name": "limit", "value": 50 } ] }, { "name": "New registrations in a block range", "description": "Find all V2 human registrations between two blocks", "params": [ { "name": "fromBlock", "value": 35000000 }, { "name": "toBlock", "value": 35100000 }, { "name": "eventTypes", "value": [ "CrcV2_RegisterHuman" ] } ] } ] }, { "name": "circles_events_paginated", "summary": "Query indexed blockchain events with cursor pagination", "description": "Returns Circles protocol events with cursor-based pagination. Response includes \u0060{events, hasMore, nextCursor}\u0060 for iterating through large result sets.\n\n**Parameters**: Same as \u0060circles_events\u0060.\n\n**Params used together**:\n- \u0060address\u0060 \u002B \u0060eventTypes\u0060: Monitor specific events for an address\n- \u0060fromBlock\u0060 \u002B \u0060toBlock\u0060: Time-range queries\n- \u0060filterPredicates\u0060: Advanced SQL-like filtering (see FilterPredicateDto schema)\n- \u0060sortAscending\u0060 \u002B \u0060limit\u0060 \u002B \u0060cursor\u0060: Pagination control", "params": [ { "name": "address", "required": false, "description": "Filter events by this address (as sender, receiver, or involved party). Null = all addresses. Case-insensitive.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "fromBlock", "required": false, "description": "Starting block number (inclusive). Combine with toBlock for time-range queries. Gnosis Chain produces ~1 block per 5 seconds.", "schema": { "type": "integer" } }, { "name": "toBlock", "required": false, "description": "Ending block number (inclusive). Null = up to the latest indexed block.", "schema": { "type": "integer" } }, { "name": "eventTypes", "required": false, "description": "Filter by event types. Examples: [\u0027CrcV2_TransferSingle\u0027,\u0027CrcV2_Trust\u0027], [\u0027CrcV1_Transfer\u0027], [\u0027CrcV2_RegisterHuman\u0027]. Null = all event types. Use circles_tables to discover all event types.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filterPredicates", "required": false, "description": "Advanced filter predicates for SQL-like filtering. Each predicate has Type, FilterType, Column, and Value. IMPORTANT: For \u0027In\u0027/\u0027NotIn\u0027 FilterType, Value MUST be an array (e.g., [\u00220xabc...\u0022]). For scalar operators (Equals, GreaterThan, etc.), Value is a single string or number. See FilterPredicateDto schema.", "schema": { "$ref": "#/components/schemas/FilterPredicateDto" } }, { "name": "sortAscending", "required": false, "description": "Sort order by block number. Default: false (newest first). Set true for chronological order. Note: this is a positional parameter \u2014 you must pass it (or null) to set limit or cursor at later positions.", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "description": "Maximum events to return per page. Default: 100, maximum: 1000. Pass null or omit to use the default of 100.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Opaque cursor from a previous response\u0027s nextCursor field for pagination. Do not construct manually.", "schema": { "type": "string" } } ], "result": { "name": "circles_events_paginatedResult", "schema": { "$ref": "#/components/schemas/PagedEventsResponse" } }, "tags": [ { "name": "Events" } ], "examples": [ { "name": "Recent transfers for an address (paginated)", "description": "Get the 50 most recent V2 transfers involving an address with pagination metadata", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "eventTypes", "value": [ "CrcV2_TransferSingle" ] }, { "name": "sortAscending", "value": false }, { "name": "limit", "value": 50 } ] }, { "name": "Paginate through registrations", "description": "Iterate through V2 human registrations with cursor-based pagination", "params": [ { "name": "fromBlock", "value": 35000000 }, { "name": "toBlock", "value": 35100000 }, { "name": "eventTypes", "value": [ "CrcV2_RegisterHuman" ] }, { "name": "limit", "value": 100 } ] } ] }, { "name": "circles_query", "summary": "Execute a structured database query (non-paginated)", "description": "Low-level query interface for direct access to indexed data tables. Uses a structured DTO (SelectDto) to specify namespace, table, columns, filters, ordering, and limits. Returns \u0060{columns, rows}\u0060 format.\n\n**Use this for**: Custom queries not covered by specific methods. Discover available tables with \u0060circles_tables\u0060.\n\n**Warning**: This is the non-paginated version. For large result sets, use \u0060circles_paginated_query\u0060 instead.", "params": [ { "name": "query", "required": true, "description": "Structured query definition specifying namespace, table, columns, filter conditions, ordering, and limit. Use circles_tables to discover available namespaces and tables.", "schema": { "$ref": "#/components/schemas/SelectDto" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response for pagination. Only works with circles_paginated_query.", "schema": { "type": "string" } } ], "result": { "name": "circles_queryResult", "schema": { "$ref": "#/components/schemas/PagedQueryResponse" } }, "tags": [ { "name": "Query" } ], "examples": [ { "name": "Query V2 trusts for an address", "description": "Low-level query to get V2 trust relations where the address is the truster", "params": [ { "name": "query", "value": { "namespace": "CrcV2", "table": "CrcV2_Trust", "columns": [ "truster", "trustee", "expiryTime" ], "filter": [ { "Type": "FilterPredicate", "Column": "truster", "FilterType": "Equals", "Value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ], "limit": 100 } } ] } ] }, { "name": "circles_paginated_query", "summary": "Execute a structured database query with cursor pagination", "description": "Server-side cursor pagination version of \u0060circles_query\u0060. Returns \u0060{columns, rows, hasMore, nextCursor}\u0060. Pass \u0060nextCursor\u0060 as the \u0060cursor\u0060 parameter in subsequent calls.\n\n**Use this for**: Iterating through large query results without loading everything into memory.\n\n**Tip**: Pair with \u0060circles_tables\u0060 to discover available tables and their columns.", "params": [ { "name": "query", "required": true, "description": "Structured query definition. Same format as circles_query but returns paginated results with cursor-based navigation.", "schema": { "$ref": "#/components/schemas/SelectDto" } }, { "name": "cursor", "required": false, "description": "Opaque cursor from the previous response\u0027s nextCursor field. Pass this to get the next page of results.", "schema": { "type": "string" } } ], "result": { "name": "circles_paginated_queryResult", "schema": { "$ref": "#/components/schemas/PagedQueryResponse" } }, "tags": [ { "name": "Query" } ], "examples": [ { "name": "Paginated transfer query", "description": "Iterate through V2 transfers with cursor pagination", "params": [ { "name": "query", "value": { "namespace": "CrcV2", "table": "CrcV2_TransferSingle", "columns": [ "from", "to", "id", "value", "blockNumber" ], "limit": 50 } } ] } ] }, { "name": "circles_getBlockByTimestamp", "summary": "Convert a Unix timestamp to the nearest block number", "description": "Returns the block number closest to the given Unix timestamp. Use \u0060direction: \u0022before\u0022\u0060 (default) for the block at or before the timestamp, or \u0060\u0022after\u0022\u0060 for the block at or after. Useful for converting human-readable date ranges into block ranges for \u0060circles_events\u0060 queries.\n\n**Common use case**: An explorer wants events between Jan 1 and Feb 1 \u2014 call this twice to get fromBlock and toBlock, then pass them to \u0060circles_events\u0060.", "params": [ { "name": "timestamp", "required": true, "description": "Unix timestamp in seconds (e.g., 1700000000 for 2023-11-14). Must be non-negative.", "schema": { "type": "integer" } }, { "name": "direction", "required": false, "description": "Lookup direction: \u0027before\u0027 (default) returns block at or before timestamp, \u0027after\u0027 returns block at or after. Useful for range queries: use \u0027after\u0027 for fromBlock, \u0027before\u0027 for toBlock.", "schema": { "type": "string" } } ], "result": { "name": "circles_getBlockByTimestampResult", "schema": { "$ref": "#/components/schemas/BlockByTimestampResponse" } }, "tags": [ { "name": "Blocks" } ], "examples": [ { "name": "Find block at a date (before)", "description": "Get the block at or before 2025-01-31 00:00:00 UTC", "params": [ { "name": "timestamp", "value": 1738281600 } ] }, { "name": "Find block at a date (after)", "description": "Get the block at or after 2025-02-28 00:00:00 UTC", "params": [ { "name": "timestamp", "value": 1740700800 }, { "name": "direction", "value": "after" } ] } ] }, { "name": "circles_health", "summary": "Check service health and sync status", "description": "Returns health information including database connectivity, blockchain sync status, current block number, and whether the service is fully caught up.\n\n**Common use case**: Health monitoring, load balancer health checks, or verifying the indexer is synced before querying.", "params": [], "result": { "name": "circles_healthResult", "schema": { "$ref": "#/components/schemas/HealthResponse" } }, "tags": [ { "name": "System" } ], "examples": [ { "name": "Check health", "description": "Verify indexer is healthy and synced", "params": [] } ] }, { "name": "circles_tables", "summary": "List available database tables and schemas", "description": "Returns all available table namespaces and their tables with column definitions. Essential reference for building \u0060circles_query\u0060 / \u0060circles_paginated_query\u0060 requests.\n\n**Common use case**: Discover what data is available for querying, including column names and types.", "params": [], "result": { "name": "circles_tablesResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TableNamespace" } } }, "tags": [ { "name": "System" } ], "examples": [ { "name": "Discover available tables", "description": "List all queryable tables and their columns", "params": [] } ] }, { "name": "circles_getProfileView", "summary": "Get a complete profile view (avatar \u002B profile \u002B trust stats \u002B balances)", "description": "Single-call replacement for 6-7 separate RPC calls when displaying a user profile. Returns avatar info, IPFS profile, trust statistics (trusting count, trusted-by count, mutual count), and balance summary.\n\n**Common use case**: Profile page rendering. Instead of calling getAvatarInfo \u002B getProfileByAddress \u002B getTrustRelations \u002B getTotalBalance separately, use this single method.\n\n**Performance**: Executes all sub-queries in parallel server-side, significantly faster than sequential client-side calls.", "params": [ { "name": "address", "required": true, "description": "Avatar address to get the consolidated profile view for. Returns avatar info, IPFS profile, trust stats, and V1/V2 balances in a single call (replaces 6-7 separate RPC calls).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getProfileViewResult", "schema": { "$ref": "#/components/schemas/ProfileViewResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Load a profile page", "description": "Get all data needed to render a profile page in one call", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getTrustNetworkSummary", "summary": "Get aggregated trust network statistics", "description": "Returns trust network metrics: total trusting, trusted-by, mutual trust count, and optional network reach at configurable depth.\n\n**Common use case**: Dashboard widgets showing network size, or determining how well-connected an avatar is.\n\n**Param**: \u0060maxDepth\u0060 controls how many hops to traverse for network reach calculation (higher = more expensive).", "params": [ { "name": "address", "required": true, "description": "Avatar address to query trust network summary for. Returns trust counts, mutual trust count, and network reach statistics.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "maxDepth", "required": false, "description": "Maximum depth for network traversal. Limits how far the trust graph is explored. Optional.", "schema": { "type": "integer" } } ], "result": { "name": "circles_getTrustNetworkSummaryResult", "schema": { "$ref": "#/components/schemas/TrustNetworkSummaryResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Trust network stats", "description": "Get trust counts and network reach for an avatar", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "maxDepth", "value": 3 } ] } ] }, { "name": "circles_getAggregatedTrustRelationsEnriched", "summary": "Get trust relations with enriched avatar info and profiles", "description": "Like \u0060circles_getAggregatedTrustRelations\u0060 but each trust relation includes the counterpart\u0027s full profile (name, image, avatar type). Paginated with cursor.\n\n**Common use case**: Render a trust list where each entry shows the avatar\u0027s name and profile picture without additional API calls.\n\n**Tip**: Use \u0060limit\u0060 to control page size (default 50, max 200).", "params": [ { "name": "address", "required": true, "description": "Avatar address to query enriched trust relations for. Returns trust relations categorized by type (mutual, one-way) with enriched avatar info.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "limit", "required": false, "description": "Maximum results per page. Default: 50, max: 200.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } } ], "result": { "name": "circles_getAggregatedTrustRelationsEnrichedResult", "schema": { "$ref": "#/components/schemas/PagedAggregatedTrustRelationsResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Trust list with profiles", "description": "Get trust relations with enriched avatar info (names, images)", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "limit", "value": 50 } ] } ] }, { "name": "circles_getValidInviters", "summary": "Get addresses that trust the given address AND have sufficient balance to invite", "description": "Finds potential sponsors for a new user: addresses that trust the target AND have enough CRC balance to fund an invitation.\n\n**Common use case**: Invitation flow \u2014 show the user who can invite them, sorted by balance.\n\n**Params used together**:\n- \u0060minimumBalance\u0060: Minimum CRC balance required (e.g., \u002796000000000000000000\u0027 for 96 CRC = 1 invitation unit)\n- \u0060limit\u0060 \u002B \u0060cursor\u0060: Pagination", "params": [ { "name": "address", "required": true, "description": "Avatar address to find valid inviters for. Returns addresses that trust this user AND have sufficient balance to sponsor an invitation.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "minimumBalance", "required": false, "description": "Minimum CRC balance required for an inviter (as string). Default: 96 CRC (1 invitation unit). Example: \u002796000000000000000000\u0027.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "description": "Maximum results per page. Default: 50, max: 200.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } } ], "result": { "name": "circles_getValidInvitersResult", "schema": { "$ref": "#/components/schemas/PagedValidInvitersResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Find sponsors with sufficient balance", "description": "Find addresses that trust this user and have at least 96 CRC (1 invitation unit)", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "minimumBalance", "value": "96000000000000000000" }, { "name": "limit", "value": 20 } ] } ] }, { "name": "circles_getTransactionHistoryEnriched", "summary": "Get transaction history with enriched participant profiles", "description": "Like \u0060circles_getTransactionHistory\u0060 but each transaction includes full profiles for all participants (sender, receiver). Eliminates the need for N additional profile lookups.\n\n**Common use case**: Transaction feed with avatars/names displayed inline.\n\n**Params used together**:\n- \u0060fromBlock\u0060 (required): Starting block number\n- \u0060toBlock\u0060 (optional): Ending block, null = latest\n- \u0060version\u0060: null = V2 only (default for backward compat), 1 = V1, 2 = V2\n- \u0060excludeIntermediary\u0060: true (default) collapses multi-hop transfers\n- \u0060limit\u0060 \u002B \u0060cursor\u0060: Pagination", "params": [ { "name": "address", "required": true, "description": "Avatar address to query enriched transaction history for. Returns transactions with participant profiles and metadata (replaces circles_events \u002B multiple getProfileByAddress calls).", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "fromBlock", "required": true, "description": "Starting block number (inclusive). Required.", "schema": { "type": "integer" } }, { "name": "toBlock", "required": false, "description": "Ending block number (inclusive). Null = up to the latest indexed block.", "schema": { "type": "integer" } }, { "name": "limit", "required": false, "description": "Maximum transactions to return. Default: 20.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } }, { "name": "version", "required": false, "description": "Filter by version: null = V2 only (backward compat), 1 = V1 only, 2 = V2 only.", "schema": { "type": "integer" } }, { "name": "excludeIntermediary", "required": false, "description": "When true (default), uses TransferSummary which excludes intermediary hop transfers.", "schema": { "type": "boolean" } } ], "result": { "name": "circles_getTransactionHistoryEnrichedResult", "schema": { "$ref": "#/components/schemas/PagedResponse_EnrichedTransaction" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Recent transactions with profiles", "description": "Get the 20 most recent V2 transactions with participant profiles", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "fromBlock", "value": 35000000 }, { "name": "limit", "value": 20 }, { "name": "version", "value": 2 }, { "name": "excludeIntermediary", "value": true } ] } ] }, { "name": "circles_searchProfileByAddressOrName", "summary": "Unified search by address prefix or name/description text", "description": "Auto-detects search type: if query starts with \u00270x\u0027, searches by address prefix; otherwise, performs full-text search on name/description. Returns paginated results with full profiles.\n\n**Common use case**: Universal search bar \u2014 users can paste an address or type a name.\n\n**Tip**: Can filter by avatar types (Human, Group, Organization) using the \u0060types\u0060 parameter.", "params": [ { "name": "query", "required": true, "description": "Search query. If starts with \u00270x\u0027, searches by address prefix. Otherwise performs full-text search across profile name and description.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "description": "Maximum results per page. Default: 20, max: 100.", "schema": { "type": "integer" } }, { "name": "cursor", "required": false, "description": "Cursor from a previous response\u0027s nextCursor field for pagination.", "schema": { "type": "string" } }, { "name": "types", "required": false, "description": "Filter by avatar types: \u0027CrcV2_RegisterHuman\u0027, \u0027CrcV2_RegisterGroup\u0027, \u0027CrcV2_RegisterOrganization\u0027. Omit for all types.", "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "circles_searchProfileByAddressOrNameResult", "schema": { "$ref": "#/components/schemas/PagedProfileSearchResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Search by address prefix", "description": "Find profiles matching an address prefix (auto-detected by 0x prefix)", "params": [ { "name": "query", "value": "0xde374ece" }, { "name": "limit", "value": 10 } ] }, { "name": "Search by name", "description": "Full-text search (auto-detected, no 0x prefix)", "params": [ { "name": "query", "value": "alice" }, { "name": "limit", "value": 10 } ] } ] }, { "name": "circles_getInvitationOrigin", "summary": "Get how an address was invited to Circles", "description": "Reconstructs the invitation chain for an address. Returns the invitation type (V1 Signup, V2 Standard, V2 Escrow, V2 At Scale), the inviter address, and related transaction details.\n\n**Common use case**: Show \u0027Invited by...\u0027 in a profile view, or tracing invitation chains for analytics.\n\n**Returns null** if the address is not registered.", "params": [ { "name": "address", "required": true, "description": "Avatar address to look up the invitation origin for. Returns how this address was invited (V1 Signup, V2 Standard, V2 Escrow, V2 At Scale) with inviter details.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getInvitationOriginResult", "schema": { "$ref": "#/components/schemas/InvitationOriginResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "How was this user invited?", "description": "Trace the invitation chain for an address", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getAllInvitations", "summary": "Get all available invitations from all sources", "description": "Aggregates invitations from all mechanisms: trust-based (addresses with sufficient balance), escrow-based (CRC escrowed for this address), and at-scale (pre-created unclaimed accounts). Single call replaces 3 separate invitation queries.\n\n**Common use case**: \u0027Accept invitation\u0027 screen showing all ways a user can join Circles.\n\n**Params used together**: \u0060minimumBalance\u0060 filters trust-based invitations by the inviter\u0027s CRC balance.", "params": [ { "name": "address", "required": true, "description": "Avatar address to query all available invitations for. Returns trust-based, escrow-based, and at-scale invitations in a single response.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "minimumBalance", "required": false, "description": "Minimum CRC balance required for trust-based invitations (as string). Example: \u002796000000000000000000\u0027 = 96 CRC.", "schema": { "type": "string" } } ], "result": { "name": "circles_getAllInvitationsResult", "schema": { "$ref": "#/components/schemas/AllInvitationsResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Get all invitation options", "description": "Find all ways a user can be invited (trust, escrow, at-scale) with minimum 96 CRC balance", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "minimumBalance", "value": "96000000000000000000" } ] } ] }, { "name": "circles_getTrustInvitations", "summary": "Get trust-based invitations", "description": "Subset of \u0060circles_getAllInvitations\u0060 \u2014 returns only trust-based invitations (addresses that trust the target and have sufficient balance).\n\n**Common use case**: When you only need trust-based invitation options.", "params": [ { "name": "address", "required": true, "description": "Avatar address to query trust-based invitations for. Returns addresses that trust this user and have sufficient balance. Subset of getAllInvitations.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "minimumBalance", "required": false, "description": "Minimum CRC balance required (as string). Default: 96 CRC. Example: \u002796000000000000000000\u0027.", "schema": { "type": "string" } } ], "result": { "name": "circles_getTrustInvitationsResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrustInvitation" } } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Trust-based invitations", "description": "Find who can invite this address via trust \u002B balance", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "minimumBalance", "value": "96000000000000000000" } ] } ] }, { "name": "circles_getEscrowInvitations", "summary": "Get escrow-based invitations", "description": "Returns CRC amounts escrowed for the target address. Filters out already redeemed, revoked, and refunded escrows server-side.\n\n**Common use case**: Check if someone has pre-funded an invitation for this address.", "params": [ { "name": "address", "required": true, "description": "Avatar address to query escrow-based invitations for. Returns CRC escrowed for this address. Filters out redeemed, revoked, and refunded escrows.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getEscrowInvitationsResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EscrowInvitation" } } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Escrow invitations", "description": "Find CRC escrowed for this address (active only)", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getAtScaleInvitations", "summary": "Get at-scale invitations", "description": "Returns pre-created accounts that haven\u0027t been claimed yet, associated with the target address.\n\n**Common use case**: Enterprise/campaign onboarding where accounts are pre-provisioned.", "params": [ { "name": "address", "required": true, "description": "Avatar address to query at-scale invitations for. Returns pre-created accounts that haven\u0027t been claimed yet.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } } ], "result": { "name": "circles_getAtScaleInvitationsResult", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AtScaleInvitation" } } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "At-scale invitations", "description": "Find pre-created accounts available for this address", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" } ] } ] }, { "name": "circles_getInvitationsFrom", "summary": "Get accounts invited by a specific avatar", "description": "Returns accounts that were invited by the given avatar. When \u0060accepted=true\u0060, shows registered accounts; when \u0060accepted=false\u0060, shows addresses this avatar trusts that are NOT yet registered (pending invitations).\n\n**Common use case**: \u0027My invitations\u0027 section showing who you\u0027ve invited and whether they\u0027ve joined.\n\n**Params used together**: \u0060accepted=false\u0060 to see pending invitations, \u0060accepted=true\u0060 to see confirmed ones.", "params": [ { "name": "address", "required": true, "description": "Inviter avatar address. When accepted=true: returns accounts that registered using this avatar as inviter. When accepted=false: returns addresses this avatar trusts that are NOT yet registered.", "schema": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } }, { "name": "accepted", "required": false, "description": "When true, returns registered (accepted) invitations. When false (default), returns pending (not yet registered) invitations.", "schema": { "type": "boolean" } } ], "result": { "name": "circles_getInvitationsFromResult", "schema": { "$ref": "#/components/schemas/InvitationsFromResponse" } }, "tags": [ { "name": "SDK" } ], "examples": [ { "name": "Pending invitations", "description": "Get addresses trusted by this avatar that haven\u0027t registered yet", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "accepted", "value": false } ] }, { "name": "Accepted invitations", "description": "Get addresses that registered using this avatar as inviter", "params": [ { "name": "address", "value": "0xde374ece6fa50e781e81aac78e811b33d16912c7" }, { "name": "accepted", "value": true } ] } ] } ], "servers": [ { "name": "Staging", "url": "https://staging.circlesubi.network" }, { "name": "Production", "url": "https://rpc.aboutcircles.com" } ], "externalDocs": { "description": "Circles RPC Host README \u2014 full method reference, filter predicates, WebSocket subscriptions, rate limiting, batch requests, and environment variables", "url": "https://github.com/aboutcircles/circles-nethermind-plugin/blob/dev/src/Rpc/Circles.Rpc.Host/README.md" }, "components": { "schemas": { "TotalBalanceResponse": { "type": "object", "properties": { "balance": { "type": "string", "description": "Aggregated total balance in CRC wei as string." } }, "required": [ "balance" ] }, "CirclesTokenBalance": { "type": "object", "properties": { "tokenAddress": { "type": "string", "description": "On-chain address of the token contract." }, "tokenId": { "type": "string", "description": "ERC-1155 token ID (same as token owner address for personal tokens)." }, "tokenOwner": { "type": "string", "description": "Avatar address that owns/minted this token." }, "tokenType": { "type": "string", "description": "Token classification: \u0027RegisterHuman\u0027, \u0027RegisterGroup\u0027, or \u0027RegisterOrganization\u0027." }, "version": { "type": "integer", "description": "Circles protocol version: 1 or 2." }, "attoCircles": { "type": "string", "description": "Balance in atto-Circles (10^-18 CRC) as string, inflationary/TimeCircles denomination." }, "circles": { "type": "number", "description": "Balance in Circles (human-readable), inflationary/TimeCircles denomination." }, "staticAttoCircles": { "type": "string", "description": "Balance in atto-Circles (10^-18 CRC) as string, demurrage-adjusted static denomination." }, "staticCircles": { "type": "number", "description": "Balance in Circles (human-readable), demurrage-adjusted static denomination." }, "attoCrc": { "type": "string", "description": "Balance in atto-CRC as string (alias for attoCircles in V2 context)." }, "crc": { "type": "number", "description": "Balance in CRC (human-readable, alias for circles in V2 context)." }, "isErc20": { "type": "boolean", "description": "True if this is an ERC-20 token." }, "isErc1155": { "type": "boolean", "description": "True if this is a native V2 ERC-1155 token." }, "isWrapped": { "type": "boolean", "description": "True if this is an ERC-20 wrapper around a V2 ERC-1155 token." }, "isInflationary": { "type": "boolean", "description": "True if the token uses inflationary denomination." }, "isGroup": { "type": "boolean", "description": "True if this token belongs to a Circles group." } }, "required": [ "tokenAddress", "tokenId", "tokenOwner", "tokenType", "version", "attoCircles", "circles", "staticAttoCircles", "staticCircles", "attoCrc", "crc", "isErc20", "isErc1155", "isWrapped", "isInflationary", "isGroup" ] }, "TokenInfo": { "type": "object", "properties": { "tokenAddress": { "type": "string", "description": "On-chain address of the token contract (ERC-1155 token ID or ERC-20 wrapper address)." }, "tokenOwner": { "type": "string", "description": "Avatar address that owns/minted this token." }, "tokenType": { "type": "string", "description": "Token classification: \u0027RegisterHuman\u0027, \u0027RegisterGroup\u0027, or \u0027RegisterOrganization\u0027." }, "version": { "type": "integer", "description": "Circles protocol version: 1 = V1 CRC token, 2 = V2 ERC-1155/ERC-20 token." }, "isErc20": { "type": "boolean", "description": "True if this is an ERC-20 token (V1 CRC or V2 wrapper)." }, "isErc1155": { "type": "boolean", "description": "True if this is a native V2 ERC-1155 token." }, "isWrapped": { "type": "boolean", "description": "True if this is an ERC-20 wrapper around a V2 ERC-1155 token." }, "isInflationary": { "type": "boolean", "description": "True if the token uses inflationary (TimeCircles) denomination." }, "isGroup": { "type": "boolean", "description": "True if this token belongs to a Circles group (minted via group trust)." } }, "required": [ "tokenAddress", "tokenOwner", "tokenType", "version", "isErc20", "isErc1155", "isWrapped", "isInflationary", "isGroup" ] }, "AvatarInfo": { "type": "object", "properties": { "version": { "type": "integer", "description": "Circles protocol version the avatar is registered under: 1 or 2." }, "type": { "type": "string", "description": "Avatar type: \u0027RegisterHuman\u0027, \u0027RegisterGroup\u0027, or \u0027RegisterOrganization\u0027." }, "avatar": { "type": "string", "description": "Ethereum address of the avatar (0x-prefixed, lowercase)." }, "tokenId": { "type": "string", "description": "Token ID associated with this avatar (personal token address)." }, "hasV1": { "type": "boolean", "description": "True if this avatar also has a V1 registration (migrated or dual-registered)." }, "v1Token": { "type": "string", "description": "V1 CRC token address, if the avatar has a V1 registration." }, "cidV0Digest": { "type": "string", "description": "Raw digest bytes of the IPFS CIDv0 for the avatar\u0027s profile (hex-encoded)." }, "cidV0": { "type": "string", "description": "IPFS CIDv0 string pointing to the avatar\u0027s profile JSON." }, "isHuman": { "type": "boolean", "description": "True if the avatar is registered as a human (not a group or organization)." }, "name": { "type": "string", "description": "Human-readable name from V2 registration (on-chain, not from IPFS profile)." }, "symbol": { "type": "string", "description": "Token symbol from V2 registration." } }, "required": [ "version", "type", "avatar", "tokenId", "hasV1", "v1Token", "cidV0Digest", "cidV0", "isHuman", "name", "symbol" ] }, "ProfileCidResponse": { "type": "object", "properties": { "cid": { "type": "string", "description": "IPFS CIDv0 string pointing to the avatar\u0027s profile JSON (null if no profile set)." } }, "required": [ "cid" ] }, "ProfileSearchResult": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of matching profiles." }, "results": { "type": "array", "description": "Array of profile search result items.", "items": { "$ref": "#/components/schemas/ProfileSearchResultItem" } } }, "required": [ "total", "results" ] }, "ProfileSearchResultItem": { "type": "object", "properties": { "avatar": { "type": "string", "description": "Ethereum address of the matched avatar." }, "avatarInfo": { "description": "Avatar registration info.", "$ref": "#/components/schemas/AvatarInfo" }, "profile": { "type": "object", "description": "IPFS profile JSON (if available).", "nullable": true } }, "required": [ "avatar", "avatarInfo" ] }, "TrustRelationsResponse": { "type": "object", "properties": { "user": { "type": "string", "description": "Address of the queried avatar." }, "trusts": { "type": "array", "description": "Addresses this avatar trusts (outgoing trust edges).", "items": { "$ref": "#/components/schemas/TrustRelation" } }, "trustedBy": { "type": "array", "description": "Addresses that trust this avatar (incoming trust edges).", "items": { "$ref": "#/components/schemas/TrustRelation" } } }, "required": [ "user", "trusts", "trustedBy" ] }, "TrustRelation": { "type": "object", "properties": { "user": { "type": "string", "description": "Address of the trusted/trusting avatar." }, "limit": { "type": "integer", "description": "Trust limit percentage (0-100). 100 = full trust, 0 = no trust." } }, "required": [ "user", "limit" ] }, "CommonTrustResponse": { "type": "object", "properties": { "address1": { "type": "string", "description": "First address in the common trust query." }, "address2": { "type": "string", "description": "Second address in the common trust query." }, "commonTrusts": { "type": "array", "description": "Array of addresses that both queried addresses have a trust relationship with.", "items": { "type": "string" } } }, "required": [ "address1", "address2", "commonTrusts" ] }, "AggregatedTrustRelation": { "type": "object", "properties": { "subjectAvatar": { "type": "string", "description": "Avatar address that is the subject of this trust relation." }, "relation": { "type": "string", "description": "Trust relation type: \u0027mutuallyTrusts\u0027, \u0027trusts\u0027, or \u0027trustedBy\u0027." }, "objectAvatar": { "type": "string", "description": "Avatar address that is the object of this trust relation." }, "timestamp": { "type": "integer", "description": "Unix timestamp when this trust relation was established." }, "expiryTime": { "type": "integer", "description": "Unix timestamp when this trust expires (0 = no expiry)." }, "objectAvatarType": { "type": "string", "description": "Type of the object avatar: \u0027Human\u0027, \u0027Group\u0027, or \u0027Organization\u0027." } }, "required": [ "subjectAvatar", "relation", "objectAvatar", "timestamp", "expiryTime", "objectAvatarType" ] }, "PagedResponse_GroupRow": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of group rows for the current page.", "items": { "$ref": "#/components/schemas/GroupRow" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "results", "hasMore", "nextCursor" ] }, "GroupRow": { "type": "object", "properties": { "group": { "type": "string", "description": "Ethereum address of the group." }, "name": { "type": "string", "description": "On-chain name of the group." }, "symbol": { "type": "string", "description": "On-chain token symbol of the group." }, "mint": { "type": "string", "description": "Mint policy contract address controlling who can mint group tokens." }, "treasury": { "type": "string", "description": "Treasury contract address holding group collateral." }, "blockNumber": { "type": "integer", "description": "Block number when the group was registered." }, "timestamp": { "type": "integer", "description": "Unix timestamp when the group was registered." } }, "required": [ "group", "name", "symbol", "mint", "treasury", "blockNumber", "timestamp" ] }, "PagedResponse_GroupMembershipRow": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of group membership rows for the current page.", "items": { "$ref": "#/components/schemas/GroupMembershipRow" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "results", "hasMore", "nextCursor" ] }, "GroupMembershipRow": { "type": "object", "properties": { "blockNumber": { "type": "integer", "description": "Block number when the membership was created." }, "timestamp": { "type": "integer", "description": "Unix timestamp when the membership was created." }, "transactionIndex": { "type": "integer", "description": "Position of the transaction within the block." }, "logIndex": { "type": "integer", "description": "Position of the log entry within the transaction receipt." }, "transactionHash": { "type": "string", "description": "Keccak-256 hash of the membership transaction." }, "group": { "type": "string", "description": "Ethereum address of the group." }, "member": { "type": "string", "description": "Ethereum address of the group member." }, "expiryTime": { "type": "integer", "description": "Unix timestamp when the membership expires (0 = no expiry)." } }, "required": [ "blockNumber", "timestamp", "transactionIndex", "logIndex", "transactionHash", "group", "member", "expiryTime" ] }, "PagedResponse_TransactionHistoryRow": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of transaction history rows for the current page.", "items": { "$ref": "#/components/schemas/TransactionHistoryRow" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "results", "hasMore", "nextCursor" ] }, "TransactionHistoryRow": { "type": "object", "properties": { "blockNumber": { "type": "integer", "description": "Gnosis Chain block number containing this transaction." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the block." }, "transactionIndex": { "type": "integer", "description": "Position of the transaction within the block." }, "logIndex": { "type": "integer", "description": "Position of the log entry within the transaction receipt." }, "transactionHash": { "type": "string", "description": "Keccak-256 hash of the transaction (0x-prefixed, 64 hex chars)." }, "version": { "type": "integer", "description": "Circles protocol version: 1 or 2." }, "from": { "type": "string", "description": "Sender address of the transfer." }, "to": { "type": "string", "description": "Receiver address of the transfer." }, "operator": { "type": "string", "description": "ERC-1155 operator address (V2 only, null for V1)." }, "id": { "type": "string", "description": "ERC-1155 token ID (V2 only, null for V1)." }, "value": { "type": "string", "description": "Transfer amount in CRC wei as string." }, "circles": { "type": "string", "description": "Transfer amount in Circles (inflationary/TimeCircles denomination)." }, "attoCircles": { "type": "string", "description": "Transfer amount in atto-Circles (inflationary denomination) as string." }, "crc": { "type": "string", "description": "Transfer amount in CRC (V2 static denomination)." }, "attoCrc": { "type": "string", "description": "Transfer amount in atto-CRC (V2 static denomination) as string." }, "staticCircles": { "type": "string", "description": "Transfer amount in static Circles (demurrage-adjusted)." }, "staticAttoCircles": { "type": "string", "description": "Transfer amount in static atto-Circles (demurrage-adjusted) as string." } }, "required": [ "blockNumber", "timestamp", "transactionIndex", "logIndex", "transactionHash", "version", "from", "to", "operator", "id", "value", "circles", "attoCircles", "crc", "attoCrc", "staticCircles", "staticAttoCircles" ] }, "PagedResponse_TransferDataRow": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of transfer data rows for the current page.", "items": { "$ref": "#/components/schemas/TransferDataRow" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "results", "hasMore", "nextCursor" ] }, "TransferDataRow": { "type": "object", "properties": { "blockNumber": { "type": "integer", "description": "Gnosis Chain block number." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the block." }, "transactionIndex": { "type": "integer", "description": "Position of the transaction within the block." }, "logIndex": { "type": "integer", "description": "Position of the log entry within the transaction receipt." }, "transactionHash": { "type": "string", "description": "Keccak-256 hash of the transaction." }, "from": { "type": "string", "description": "Sender address." }, "to": { "type": "string", "description": "Receiver address." }, "data": { "type": "string", "description": "Hex-encoded bytes of the transfer data payload." } }, "required": [ "blockNumber", "timestamp", "transactionIndex", "logIndex", "transactionHash", "from", "to", "data" ] }, "PagedResponse_TokenHolderRow": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of token holder rows for the current page.", "items": { "$ref": "#/components/schemas/TokenHolderRow" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "results", "hasMore", "nextCursor" ] }, "TokenHolderRow": { "type": "object", "properties": { "account": { "type": "string", "description": "Ethereum address of the token holder." }, "balance": { "type": "string", "description": "Token balance in CRC wei as string." }, "tokenAddress": { "type": "string", "description": "Address of the held token contract." }, "version": { "type": "integer", "description": "Circles protocol version: 1 or 2." } }, "required": [ "account", "balance", "tokenAddress", "version" ] }, "PagedEventsResponse": { "type": "object", "properties": { "events": { "type": "array", "description": "Array of event objects for the current page.", "items": { "$ref": "#/components/schemas/Object" } }, "hasMore": { "type": "boolean", "description": "True if more events exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "events", "hasMore", "nextCursor" ] }, "Object": { "type": "object" }, "PagedQueryResponse": { "type": "object", "properties": { "columns": { "type": "array", "description": "Column names for the result set.", "items": { "type": "string" } }, "rows": { "type": "array", "description": "Array of row arrays, each containing values in column order.", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Object" } } }, "hasMore": { "type": "boolean", "description": "True if more rows exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "columns", "rows", "hasMore", "nextCursor" ] }, "BlockByTimestampResponse": { "type": "object", "properties": { "blockNumber": { "type": "integer" }, "timestamp": { "type": "integer" } }, "required": [ "blockNumber", "timestamp" ] }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "Overall health status: \u0027healthy\u0027, \u0027degraded\u0027, or \u0027unhealthy\u0027." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the health check." }, "database": { "type": "string", "description": "Database connectivity status." }, "index": { "type": "string", "description": "Index synchronization status." } }, "required": [ "status", "timestamp", "database", "index" ] }, "TableNamespace": { "type": "object", "properties": { "namespace": { "type": "string", "description": "Schema namespace grouping related tables (e.g., \u0027CrcV1\u0027, \u0027CrcV2\u0027)." }, "tables": { "type": "array", "description": "Array of table definitions within this namespace.", "items": { "$ref": "#/components/schemas/TableDefinition" } } }, "required": [ "namespace", "tables" ] }, "TableDefinition": { "type": "object", "properties": { "table": { "type": "string", "description": "Table name within the namespace." }, "topic": { "type": "string", "description": "Event topic this table indexes." }, "columns": { "type": "array", "description": "Array of column definitions for this table.", "items": { "$ref": "#/components/schemas/TableColumn" } } }, "required": [ "table", "topic", "columns" ] }, "TableColumn": { "type": "object", "properties": { "column": { "type": "string", "description": "Column name." }, "type": { "type": "string", "description": "PostgreSQL column type (e.g., \u0027text\u0027, \u0027bigint\u0027, \u0027boolean\u0027)." } }, "required": [ "column", "type" ] }, "ProfileViewResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Ethereum address of the avatar." }, "avatarInfo": { "description": "Full avatar registration info.", "$ref": "#/components/schemas/AvatarInfo" }, "profile": { "type": "object", "description": "IPFS profile JSON (if available).", "nullable": true }, "trustStats": { "description": "Trust relationship counts (trusts/trustedBy).", "$ref": "#/components/schemas/TrustStats" }, "v1Balance": { "type": "string", "description": "V1 CRC balance as string (null if no V1 registration)." }, "v2Balance": { "type": "string", "description": "V2 CRC balance as string (null if no V2 registration)." } } }, "TrustStats": { "type": "object", "properties": { "trustsCount": { "type": "integer", "description": "Number of avatars this address trusts (outgoing)." }, "trustedByCount": { "type": "integer", "description": "Number of avatars that trust this address (incoming)." } } }, "TrustNetworkSummaryResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Ethereum address of the queried avatar." }, "directTrustsCount": { "type": "integer", "description": "Number of avatars this address directly trusts." }, "directTrustedByCount": { "type": "integer", "description": "Number of avatars that directly trust this address." }, "mutualTrustsCount": { "type": "integer", "description": "Number of mutual trust relationships." }, "mutualTrusts": { "type": "array", "description": "Array of addresses with mutual trust.", "items": { "type": "string" } }, "networkReach": { "type": "integer", "description": "Estimated number of avatars reachable via transitive trust." } } }, "PagedAggregatedTrustRelationsResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the queried avatar." }, "results": { "type": "array", "description": "Array of trust relation info objects for the current page.", "items": { "$ref": "#/components/schemas/TrustRelationInfo" } }, "counts": { "description": "Summary counts of trust relations by type.", "$ref": "#/components/schemas/TrustRelationCounts" }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } } }, "TrustRelationInfo": { "type": "object", "properties": { "address": { "type": "string", "description": "Ethereum address of the related avatar." }, "avatarInfo": { "description": "Full avatar registration info for the related address.", "$ref": "#/components/schemas/AvatarInfo" }, "relationType": { "type": "string", "description": "Relation type: \u0027mutual\u0027, \u0027trusts\u0027, or \u0027trustedBy\u0027." } } }, "TrustRelationCounts": { "type": "object", "properties": { "mutual": { "type": "integer", "description": "Number of mutual trust relationships." }, "trusts": { "type": "integer", "description": "Number of outgoing trust relationships (this avatar trusts them)." }, "trustedBy": { "type": "integer", "description": "Number of incoming trust relationships (they trust this avatar)." }, "total": { "type": "integer", "description": "Total trust relationships across all types." } } }, "PagedValidInvitersResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the account being checked for valid inviters." }, "results": { "type": "array", "description": "Array of valid inviter info objects for the current page.", "items": { "$ref": "#/components/schemas/InviterInfo" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } } }, "InviterInfo": { "type": "object", "properties": { "address": { "type": "string", "description": "Ethereum address of the potential inviter." }, "balance": { "type": "string", "description": "Inviter\u0027s CRC balance relevant to invitation capability (CRC wei string)." }, "avatarInfo": { "description": "Avatar registration info for the inviter.", "$ref": "#/components/schemas/AvatarInfo" } } }, "PagedResponse_EnrichedTransaction": { "type": "object", "properties": { "results": { "type": "array", "description": "Array of enriched transaction objects for the current page.", "items": { "$ref": "#/components/schemas/EnrichedTransaction" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } }, "required": [ "results", "hasMore", "nextCursor" ] }, "EnrichedTransaction": { "type": "object", "properties": { "blockNumber": { "type": "integer", "description": "Gnosis Chain block number." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the block." }, "transactionHash": { "type": "string", "description": "Keccak-256 hash of the transaction." }, "transactionIndex": { "type": "integer", "description": "Position of the transaction within the block." }, "logIndex": { "type": "integer", "description": "Position of the log entry within the transaction receipt." }, "event": { "type": "object", "description": "Raw event data as JSON object." }, "participants": { "type": "object", "description": "Map of participant address \u2192 profile/avatar info for all addresses involved in this event.", "additionalProperties": { "$ref": "#/components/schemas/ParticipantInfo" } } } }, "ParticipantInfo": { "type": "object", "properties": { "avatarInfo": { "description": "Avatar registration info for the participant.", "$ref": "#/components/schemas/AvatarInfo" }, "profile": { "type": "object", "description": "IPFS profile JSON for the participant (if available).", "nullable": true } } }, "PagedProfileSearchResponse": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query that was executed." }, "searchType": { "type": "string", "description": "Search type used: \u0027address\u0027 (prefix match) or \u0027text\u0027 (name/description search)." }, "results": { "type": "array", "description": "Array of matching profile JSON objects.", "items": { "type": "object", "description": "Arbitrary JSON value" } }, "hasMore": { "type": "boolean", "description": "True if more results exist beyond this page." }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page." } } }, "InvitationOriginResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the invited avatar." }, "invitationType": { "type": "string", "description": "How the avatar was invited: \u0027v1_signup\u0027, \u0027v2_standard\u0027, \u0027v2_escrow\u0027, or \u0027v2_at_scale\u0027." }, "inviter": { "type": "string", "description": "Address of the direct inviter (null if unknown)." }, "proxyInviter": { "type": "string", "description": "Address of the proxy inviter for escrow invitations." }, "escrowAmount": { "type": "string", "description": "Amount escrowed for escrow invitations (CRC wei string)." }, "blockNumber": { "type": "integer", "description": "Block number when the invitation occurred." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the invitation." }, "transactionHash": { "type": "string", "description": "Transaction hash of the invitation event." }, "version": { "type": "integer", "description": "Circles protocol version: 1 or 2." } }, "required": [ "address", "invitationType", "inviter", "proxyInviter", "escrowAmount", "blockNumber", "timestamp", "transactionHash", "version" ] }, "AllInvitationsResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the queried inviter." }, "trustInvitations": { "type": "array", "description": "Invitations via direct trust (the inviter trusts the invitee).", "items": { "$ref": "#/components/schemas/TrustInvitation" } }, "escrowInvitations": { "type": "array", "description": "Invitations via CRC escrow deposit.", "items": { "$ref": "#/components/schemas/EscrowInvitation" } }, "atScaleInvitations": { "type": "array", "description": "Invitations via the at-scale invitation mechanism.", "items": { "$ref": "#/components/schemas/AtScaleInvitation" } } } }, "TrustInvitation": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the invited avatar." }, "source": { "type": "string", "description": "Invitation source type (always \u0027trust\u0027)." }, "balance": { "type": "string", "description": "Current CRC balance of the inviter relevant to this invitation (CRC wei string)." }, "avatarInfo": { "description": "Avatar info of the invited account (if registered).", "$ref": "#/components/schemas/AvatarInfo" } } }, "EscrowInvitation": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the invited avatar." }, "source": { "type": "string", "description": "Invitation source type (always \u0027escrow\u0027)." }, "escrowedAmount": { "type": "string", "description": "Amount of CRC escrowed for this invitation (CRC wei string)." }, "escrowDays": { "type": "integer", "description": "Number of days the CRC is escrowed before release." }, "blockNumber": { "type": "integer", "description": "Block number when the escrow was created." }, "timestamp": { "type": "integer", "description": "Unix timestamp when the escrow was created." }, "avatarInfo": { "description": "Avatar info of the invited account (if registered).", "$ref": "#/components/schemas/AvatarInfo" } } }, "AtScaleInvitation": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the invited avatar." }, "source": { "type": "string", "description": "Invitation source type (always \u0027atScale\u0027)." }, "blockNumber": { "type": "integer", "description": "Block number of the at-scale invitation event." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the at-scale invitation event." }, "originInviter": { "type": "string", "description": "Original inviter address in the invitation chain." } } }, "InvitationsFromResponse": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the queried inviter." }, "accepted": { "type": "boolean", "description": "Filter applied: true = registered invitees, false = pending invitees." }, "results": { "type": "array", "description": "List of invited accounts matching the filter.", "items": { "$ref": "#/components/schemas/InvitedAccountInfo" } } } }, "InvitedAccountInfo": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the invited account." }, "status": { "type": "string", "description": "Invitation status: \u0027accepted\u0027 (registered) or \u0027pending\u0027 (not yet registered)." }, "blockNumber": { "type": "integer", "description": "Block number of the invitation event." }, "timestamp": { "type": "integer", "description": "Unix timestamp of the invitation event." }, "avatarInfo": { "description": "Avatar info if the invited account has registered.", "$ref": "#/components/schemas/AvatarInfo" } } }, "SimulatedBalance": { "type": "object", "properties": { "holder": { "type": "string", "description": "Holder address \u2014 the avatar that holds the tokens (0x-prefixed)." }, "token": { "type": "string", "description": "Token identifier \u2014 the token-owner avatar address, or ERC-20 wrapper address." }, "amount": { "type": "string", "description": "Balance amount as uint256 string in CRC wei. Example: \u002296000000000000000000\u0022 = 96 CRC." }, "isWrapped": { "type": "boolean", "description": "When true, treat as an ERC-20 wrapped token balance instead of native ERC-1155.", "nullable": true }, "isStatic": { "type": "boolean", "description": "When true, this balance is not subject to demurrage decay.", "nullable": true } } }, "SimulatedTrust": { "type": "object", "properties": { "truster": { "type": "string", "description": "The address that grants trust (0x-prefixed, 40 hex chars)." }, "trustee": { "type": "string", "description": "The address that receives trust (0x-prefixed, 40 hex chars)." } } }, "FlowRequest": { "type": "object", "properties": { "source": { "type": "string", "description": "Sender address (0x-prefixed, 40 hex chars). Must be a registered Circles V2 avatar." }, "sink": { "type": "string", "description": "Receiver address (0x-prefixed, 40 hex chars). Must be a registered Circles V2 avatar." }, "targetFlow": { "type": "string", "description": "Amount to transfer in CRC wei (1 CRC = 10^18 wei). Use max uint256 to discover maximum possible flow." }, "toTokens": { "type": "array", "description": "Restrict which tokens the sink can receive. Array of token-owner addresses.", "items": { "type": "string" } }, "fromTokens": { "type": "array", "description": "Restrict which tokens the source can send. Array of token-owner addresses.", "items": { "type": "string" } }, "excludedFromTokens": { "type": "array", "description": "Exclude specific tokens from the source side. Array of token-owner addresses.", "items": { "type": "string" } }, "excludedToTokens": { "type": "array", "description": "Exclude specific tokens from the sink side. Array of token-owner addresses.", "items": { "type": "string" } }, "withWrap": { "type": "boolean", "description": "When true, includes ERC-20 wrapper token paths in addition to native ERC-1155 paths.", "nullable": true }, "simulatedBalances": { "type": "array", "description": "Hypothetical token balances to inject into the graph before path computation.", "items": { "$ref": "#/components/schemas/SimulatedBalance" } }, "simulatedTrusts": { "type": "array", "description": "Hypothetical trust relations to inject into the graph before path computation.", "items": { "$ref": "#/components/schemas/SimulatedTrust" } }, "simulatedConsentedAvatars": { "type": "array", "description": "Addresses to treat as having consented to advanced usage (ERC-1155 operator approval).", "items": { "type": "string" } }, "maxTransfers": { "type": "integer", "description": "Maximum number of transfer steps in the result. Limits path complexity for on-chain gas cost control.", "nullable": true }, "quantizedMode": { "type": "boolean", "description": "When true, enforces 96 CRC quantization for sink-bound transfers (invitation module). Each transfer = N \u00D7 96 CRC.", "nullable": true }, "debugShowIntermediateSteps": { "type": "boolean", "description": "When true, includes debug info showing all transformation stages: rawPaths, collapsed, routerInserted, sorted.", "nullable": true } } }, "TransferPathStep": { "type": "object", "properties": { "from": { "type": "string", "description": "Sender address for this transfer step (0x-prefixed, lowercase)." }, "to": { "type": "string", "description": "Receiver address for this transfer step (0x-prefixed, lowercase)." }, "tokenOwner": { "type": "string", "description": "Token owner address identifying which Circles token is transferred." }, "value": { "type": "string", "description": "Transfer amount in CRC wei (uint256 as decimal string)." } } }, "MaxFlowResponse": { "type": "object", "properties": { "maxFlow": { "type": "string", "description": "Maximum achievable flow in CRC wei (uint256 as decimal string)." }, "transfers": { "type": "array", "description": "Ordered list of individual token transfer steps to submit on-chain via Hub.sol operateFlowMatrix().", "items": { "$ref": "#/components/schemas/TransferPathStep" } } }, "required": [ "maxFlow", "transfers" ] }, "FilterPredicateDto": { "type": "object", "description": "See IFilterPredicateDto for structure" }, "IFilterPredicateDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Discriminator for filter predicate polymorphism. Value: \u0027FilterPredicate\u0027." } } }, "OrderByDto": { "type": "object", "properties": { "column": { "type": "string", "description": "Column name to sort by." }, "sortOrder": { "type": "string", "description": "Sort direction: \u0027ASC\u0027 (ascending) or \u0027DESC\u0027 (descending)." } } }, "SelectDto": { "type": "object", "properties": { "namespace": { "type": "string", "description": "Database namespace to query (e.g., \u0027CrcV1\u0027, \u0027CrcV2\u0027, \u0027V_CrcV1\u0027, \u0027V_CrcV2\u0027)." }, "table": { "type": "string", "description": "Table name within the namespace." }, "columns": { "type": "array", "description": "Column names to return. Omit or empty for all columns.", "items": { "type": "string" } }, "filter": { "type": "array", "description": "Array of filter predicates to apply (AND logic).", "items": { "$ref": "#/components/schemas/IFilterPredicateDto" } }, "order": { "type": "array", "description": "Array of ordering directives.", "items": { "$ref": "#/components/schemas/OrderByDto" } }, "limit": { "type": "integer", "description": "Maximum rows to return (default: 50, max: 200).", "nullable": true }, "distinct": { "type": "boolean", "description": "When true, return only distinct rows." } } } } } }