Circles API

Get all token balances with metadata

post

Returns all token balances of an address with full metadata. Each row includes flags (isWrapped, isGroup, isInflationary, isErc20, isErc1155, tokenType) for client-side filtering, plus balances in several denominations (attoCircles/circles, staticAttoCircles/staticCircles, attoCrc/crc).

Positional params:

1. address (string, required) — Address to get balances for.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of token balance rows.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTokenBalances

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTokenBalances", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Array of token balance rows.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "tokenAddress": "0x7147a7405fcfe5cfa30c6d5363f9f357a317d082",
      "tokenId": "0x7147a7405fcfe5cfa30c6d5363f9f357a317d082",
      "tokenOwner": "0x86533d1ada8ffbe7b6f7244f9a1b707f7f3e239b",
      "tokenType": "CrcV2_ERC20WrapperDeployed_Inflationary",
      "version": 2,
      "attoCircles": "379996949295510643539773",
      "circles": 379996.94929551065,
      "staticAttoCircles": "571956288511002296462231",
      "staticCircles": 571956.2885110023,
      "attoCrc": "185562349554202121661784",
      "crc": 185562.3495542021,
      "isErc20": true,
      "isErc1155": false,
      "isWrapped": true,
      "isInflationary": true,
      "isGroup": true
    }
  ]
}

Get metadata for a token

post

Returns metadata for a single Circles token.

Positional params:

1. tokenAddress (string, required) — Token contract address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Token metadata object.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTokenInfo

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTokenInfo", "params": ["0x7147a7405fcfe5cfa30c6d5363f9f357a317d082"]}'

200

Token metadata object.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tokenAddress": "0x7147a7405fcfe5cfa30c6d5363f9f357a317d082",
    "tokenOwner": "0x86533d1ada8ffbe7b6f7244f9a1b707f7f3e239b",
    "tokenType": "CrcV2_ERC20WrapperDeployed_Inflationary",
    "version": 2,
    "isErc20": true,
    "isErc1155": false,
    "isWrapped": true,
    "isInflationary": true,
    "isGroup": true
  }
}

Get metadata for multiple tokens

post

Batch variant of circles_getTokenInfo.

Positional params:

1. tokenAddresses (string[], required) — Array of token contract addresses.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of token metadata objects (one per input address).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTokenInfoBatch

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTokenInfoBatch", "params": [["0x7147a7405fcfe5cfa30c6d5363f9f357a317d082", "0xc19bc204eb1c1d5b3fe500e5e5dfabab625f286c"]]}'

200

Array of token metadata objects (one per input address).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "tokenAddress": "0x7147a7405fcfe5cfa30c6d5363f9f357a317d082",
      "tokenOwner": "0x86533d1ada8ffbe7b6f7244f9a1b707f7f3e239b",
      "tokenType": "CrcV2_ERC20WrapperDeployed_Inflationary",
      "version": 2,
      "isErc20": true,
      "isWrapped": true,
      "isGroup": true
    }
  ]
}

Get avatar info

post

Returns avatar information for an address (V1 and V2 merged): version, type, token id, whether it has a V1 token, and its profile CID (if any).

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Avatar info object (or null if not signed up).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getAvatarInfo

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getAvatarInfo", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Avatar info object (or null if not signed up).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "version": 2,
    "type": "CrcV2_RegisterHuman",
    "avatar": "0x42cedde51198d1773590311e2a340dc06b24cb37",
    "tokenId": "0x42cedde51198d1773590311e2a340dc06b24cb37",
    "hasV1": false,
    "cidV0Digest": "",
    "cidV0": "QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy",
    "isHuman": true,
    "symbol": ""
  }
}

Get avatar info for multiple addresses

post

Batch variant of circles_getAvatarInfo.

Positional params:

1. addresses (string[], required) — Array of avatar addresses.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of avatar info objects.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getAvatarInfoBatch

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getAvatarInfoBatch", "params": [["0x42cEDde51198D1773590311E2A340DC06B24cB37", "0x749c930256B47049cb65adFD39d8e3DD22A4d4Bd"]]}'

200

Array of avatar info objects.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "version": 2,
      "type": "CrcV2_RegisterHuman",
      "avatar": "0x42cedde51198d1773590311e2a340dc06b24cb37",
      "tokenId": "0x42cedde51198d1773590311e2a340dc06b24cb37",
      "hasV1": false,
      "isHuman": true,
      "cidV0": "QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy"
    }
  ]
}

Get profile by address

post

Returns the profile for an avatar address. May also include extended group-profile fields when set: externalLinks.website, membershipCriteria.{minRepScore, membershipFee, additionalCriteria}, groupType, contactInfo.{email, website}.

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Profile object (or null if none).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileByAddress

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileByAddress", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Profile object (or null if none).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cedde51198d1773590311e2a340dc06b24cb37",
    "name": "martin",
    "@type": "Profile",
    "description": "yo",
    "previewImageUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/…(truncated)"
  }
}

Get profiles for multiple addresses

post

Batch variant of circles_getProfileByAddress. Extended group-profile fields may be present per item.

Positional params:

1. addresses (string[], required) — Array of avatar addresses.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of profile objects (one per input address; null when none).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileByAddressBatch

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileByAddressBatch", "params": [["0x42cEDde51198D1773590311E2A340DC06B24cB37"]]}'

200

Array of profile objects (one per input address; null when none).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0x42cedde51198d1773590311e2a340dc06b24cb37",
      "name": "martin",
      "@type": "Profile",
      "description": "yo"
    }
  ]
}

Get profile IPFS CID

post

Returns the IPFS CIDv0 of an avatar's profile.

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

CIDv0 string (or null).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileCid

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileCid", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

CIDv0 string (or null).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy"
}

Get profile IPFS CIDs (batch)

post

Batch variant of circles_getProfileCid.

Positional params:

1. addresses (string[], required) — Array of avatar addresses.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of CIDv0 strings (one per input address; null when none).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileCidBatch

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileCidBatch", "params": [["0x42cEDde51198D1773590311E2A340DC06B24cB37"]]}'

200

Array of CIDv0 strings (one per input address; null when none).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy"
  ]
}

Get profile by IPFS CID

post

Retrieves a profile from IPFS by its CID.

Positional params:

1. cid (string, required) — CIDv0 string.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Profile object.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileByCid

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileByCid", "params": ["QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy"]}'

200

Profile object.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "name": "martin",
    "@type": "Profile",
    "description": "yo"
  }
}

Get profiles by IPFS CIDs (batch)

post

Batch variant of circles_getProfileByCid.

Positional params:

1. cids (string[], required) — Array of IPFS CIDs.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of profile objects.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileByCidBatch

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileByCidBatch", "params": [["QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy"]]}'

200

Array of profile objects.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "martin",
      "@type": "Profile",
      "description": "yo"
    }
  ]
}

Full-text profile search

post

Full-text search for profiles. Each result's Profile sub-object may include extended group fields (flat shape): externalWebsite, minRepScore, membershipFee, additionalCriteria, groupType, contactEmail, contactWebsite.

Positional params:

1. text (string, required) — Search query (max 3 tokens).

2. limit (integer, optional, default 20) — Max results (max 100).

3. offset (integer, optional, default 0) — Pagination offset.

4. types (string[], optional) — Filter by avatar types.

5. groupType (string, optional) — Filter by group type: open or closed.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of matching profiles.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_searchProfiles

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_searchProfiles", "params": ["martin", 20]}'

200

Array of matching profiles.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0x04a49e95a3d2e5c480580e47a335c1ff5327dd1e",
      "cid": "QmXnbzchGyyhRCQLf3k481Vw8kGKxz63Pi8oViggyYTCBd",
      "name": "Martin-TEST",
      "avatarType": "CrcV2_RegisterHuman"
    },
    {
      "address": "0x846c3eaad64a3085878ffc98a925558d32b5cc34",
      "cid": "QmUz7138mUZHE2UWmuDVSyD5V4NgCC4b2rY6rtXjx8f6hJ",
      "name": "Jose Martinez",
      "avatarType": "CrcV2_RegisterHuman"
    }
  ]
}

Unified search by address or name

post

Unified search by address prefix or name/text. A 0x prefix triggers address search.

Positional params:

1. query (string, required) — Search query (0x… ⇒ address search).

2. limit (integer, optional, default 20) — Max results.

3. cursor (string, optional) — Pagination cursor.

4. types (string[], optional) — Filter by avatar types.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Search result with detected searchType and matched profiles.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_searchProfileByAddressOrName

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_searchProfileByAddressOrName", "params": ["martin", 20]}'

200

Search result with detected searchType and matched profiles.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "query": "martin",
    "searchType": "text",
    "results": [
      {
        "name": "martin",
        "namespaces": {
          "0x37f6819d7c767ea831d8c0e0170b46e6ccbfa304": "QmREWSFooLY7pmFBmh82BAQQSyw7ihYSU6qesX3dZzzPwo"
        },
        "description": "yo",
        "signingKeys": {},
        "previewImageUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/…(truncated)"
      }
    ]
  }
}

Get trust relations

post

Returns the trust relationships for an address as a list of outgoing trusts with limits.

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Trust relations for the user.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTrustRelations

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTrustRelations", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Trust relations for the user.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "user": "0x42cedde51198d1773590311e2a340dc06b24cb37",
    "trusts": [
      {
        "user": "0x00177c523fb0243dc365a684b2ad48c9e2b4a758",
        "limit": 100
      },
      {
        "user": "0x00aea212779f90d289ec0b97c85e2a220351dee7",
        "limit": 50
      }
    ]
  }
}

Get aggregated trust relations

post

Returns aggregated trust relations in SDK-compatible format. relation is one of trusts, trustedBy, mutuallyTrusts, selfTrusts.

Positional params:

1. avatar (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of aggregated trust relation rows.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getAggregatedTrustRelations

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getAggregatedTrustRelations", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Array of aggregated trust relation rows.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "subjectAvatar": "0x42cedde51198d1773590311e2a340dc06b24cb37",
      "relation": "trustedBy",
      "objectAvatar": "0x6f10a6317efda89a2504406bf4520e72ec400537",
      "timestamp": 1780509575,
      "expiryTime": 9223372036854776000,
      "objectAvatarType": "CrcV2_RegisterHuman"
    }
  ]
}

Get common trust between two addresses

post

Finds addresses that two users both trust.

Positional params:

1. address1 (string, required) — First address.

2. address2 (string, required) — Second address.

3. version (integer, optional) — Filter by version (1, 2, or null for both).

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of commonly-trusted addresses (empty if none).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getCommonTrust

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getCommonTrust", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", "0x749c930256B47049cb65adFD39d8e3DD22A4d4Bd"]}'

200

Array of commonly-trusted addresses (empty if none).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": []
}

Get group members

post

Returns members of a specific group, paginated.

Positional params:

1. groupAddress (string, required) — Group address.

2. limit (integer, optional, default 100) — Max results.

3. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Paginated list of group memberships.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getGroupMembers

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getGroupMembers", "params": ["0xc19bc204eb1c1d5b3fe500e5e5dfabab625f286c", 100]}'

200

Paginated list of group memberships.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      {
        "blockNumber": 46385755,
        "timestamp": 1779865260,
        "transactionHash": "0x73937a961ce36418548778bdcee43a3083a11e628551de8017359322c912adad",
        "group": "0xc19bc204eb1c1d5b3fe500e5e5dfabab625f286c",
        "member": "0x8b4679cd1064691a661e63dfdaaae5e4dbb4997d",
        "expiryTime": 9223372036854776000
      }
    ],
    "hasMore": true,
    "nextCursor": "NDYzODUzMDQ6NDox"
  }
}

Get group memberships of an avatar

post

Returns the groups that an avatar is a member of.

Positional params:

1. memberAddress (string, required) — Member address.

2. limit (integer, optional, default 50) — Max results.

3. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Paginated list of group memberships.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getGroupMemberships

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getGroupMemberships", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", 50]}'

200

Paginated list of group memberships.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      {
        "blockNumber": 46505393,
        "timestamp": 1780482155,
        "group": "0xcd4440eafd274668af29ffcfa51fdec3b3b0ed9c",
        "member": "0x42cedde51198d1773590311e2a340dc06b24cb37",
        "expiryTime": 2095842147
      }
    ],
    "hasMore": true,
    "nextCursor": "NDY0Mzk4NDU6MToz"
  }
}

Get score-group mint limits

post

Returns per-(group, collateral) headroom for score-group mints. Passing a collateralToken returns a single row.

Positional params:

1. group (string, required) — Score-group address.

2. collateralToken (string, optional) — Collateral token filter.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Mint-limit rows for the group.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getScoreGroupMintLimits

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getScoreGroupMintLimits", "params": ["0xcd4440eafd274668af29ffcfa51fdec3b3b0ed9c"]}'

200

Mint-limit rows for the group.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "group": "0xcd4440eafd274668af29ffcfa51fdec3b3b0ed9c",
    "rows": []
  }
}

Get a full trust-network snapshot

post

Returns a complete snapshot of the Circles trust network. This response is large.

Positional params: none.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Full network snapshot (shape illustrative — fields may vary).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getNetworkSnapshot

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getNetworkSnapshot", "params": []}'

200

Full network snapshot (shape illustrative — fields may vary).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockNumber": 46522313,
    "avatars": [
      "0x…"
    ],
    "balances": [
      "…"
    ],
    "trustEdges": [
      "…"
    ]
  }
}

Get transaction history

post

Returns incoming and outgoing Circles transfers for an avatar (mints and transfers, V1 and V2). Results are ordered descending.

Positional params:

1. avatarAddress (string, required) — Avatar address.

2. limit (integer, optional, default 50) — Max transactions.

3. cursor (string, optional) — Pagination cursor.

4. version (integer, optional) — Filter by version (null = both).

5. excludeIntermediary (boolean, optional, default true) — Exclude intermediary hops.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Transaction rows.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTransactionHistory

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTransactionHistory", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", 50]}'

200

Transaction rows.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      {
        "blockNumber": 46519123,
        "timestamp": 1780553485,
        "transactionHash": "0xde9182d84e2643d8f8e8630584c92b78feaced1653b320627e18e5235bd291a8",
        "version": 2,
        "from": "0x49af5823767e3f328e3767a00178ac5998a7ee67",
        "to": "0x42cedde51198d1773590311e2a340dc06b24cb37",
        "value": "3166004466341249700",
        "circles": "3.1660044663412497",
        "attoCircles": "3166004466341249700",
        "crc": "1.545987898139128998",
        "staticCircles": "4.765343951668379717"
      }
    ]
  }
}

Get enriched transaction history

post

Transaction history enriched with participant profiles, over a block range.

Positional params:

1. address (string, required) — Avatar address.

2. fromBlock (integer, required) — Starting block number.

3. toBlock (integer, optional) — Ending block number.

4. limit (integer, optional, default 20) — Max transactions.

5. cursor (string, optional) — Pagination cursor.

6. version (integer, optional) — Filter by version.

7. excludeIntermediary (boolean, optional, default true) — Exclude intermediary hops.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Enriched transaction rows (shape illustrative; like circles_getTransactionHistory rows plus fromProfile/toProfile).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTransactionHistoryEnriched

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTransactionHistoryEnriched", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", 46500000, null, 20]}'

200

Enriched transaction rows (shape illustrative; like circles_getTransactionHistory rows plus fromProfile/toProfile).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      {
        "blockNumber": 46519123,
        "timestamp": 1780553485,
        "from": "0x49af5823767e3f328e3767a00178ac5998a7ee67",
        "to": "0x42cedde51198d1773590311e2a340dc06b24cb37",
        "value": "3166004466341249700",
        "fromProfile": {
          "name": "alice",
          "@type": "Profile"
        },
        "toProfile": {
          "name": "martin",
          "@type": "Profile"
        }
      }
    ],
    "hasMore": false
  }
}

Get token holders

post

Returns all holders of a specific token, paginated.

Positional params:

1. tokenAddress (string, required) — Token address.

2. limit (integer, optional, default 100) — Max holders.

3. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Paginated list of token holders.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTokenHolders

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTokenHolders", "params": ["0xc19bc204eb1c1d5b3fe500e5e5dfabab625f286c", 100]}'

200

Paginated list of token holders.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      {
        "account": "0x000e7af46fd72d4613e9e31add57565e5c9639a8",
        "balance": "1072",
        "tokenAddress": "0xc19bc204eb1c1d5b3fe500e5e5dfabab625f286c",
        "version": 2
      }
    ],
    "hasMore": true,
    "nextCursor": "0x0011a6740e9c340231fdc8f59f0f98452c4f55e8"
  }
}

Get ERC-1155 transfer data bytes

post

Returns the data bytes parameter from ERC-1155 transfer calls. See the CrcV2_TransferData tutorial for decoding annotated payloads.

Positional params:

1. address (string, required) — Primary address to filter.

2. direction (string, optional) — "sent", "received", or null (both).

3. counterparty (string, optional) — Counterparty address filter.

4. fromBlock (integer, optional) — Start block (inclusive).

5. toBlock (integer, optional) — End block (inclusive).

6. limit (integer, optional, default 50) — Max results (max 1000).

7. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Transfers carrying a non-empty data field.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTransferData

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTransferData", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", null, null, null, null, 50]}'

200

Transfers carrying a non-empty data field.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": [
      {
        "blockNumber": 46441517,
        "timestamp": 1780152575,
        "transactionHash": "0xc46186f81272cd6dcecfb33765e550ccff0964751b5857cc30581fb02bf8bf36",
        "from": "0x6a5f8aaf34487de8275c0b46cd92cd84b645a850",
        "to": "0x42cedde51198d1773590311e2a340dc06b24cb37",
        "data": "0x010001000b63347562693a73706c6974"
      }
    ]
  }
}

Query indexed blockchain events

post

Queries indexed blockchain events with advanced filtering.

Positional params:

1. address (string, optional) — Filter by address.

2. fromBlock (integer, optional) — Starting block (inclusive).

3. toBlock (integer, optional) — Ending block (inclusive).

4. eventTypes (string[], optional) — Filter by event types (e.g. CrcV2_TransferSingle).

5. filterPredicates (object[], optional) — Advanced filter predicates.

6. sortAscending (boolean, optional, default false) — Sort order.

7. limit (integer, optional, default 100) — Max events (max 1000).

8. cursor (string, optional) — Pagination cursor.

Event types include the CrcV1_*, CrcV2_* and CrcV2_ScoreGroup_* families — see circles_tables for the full catalog.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of events with event name and values payload (hex-encoded numerics).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_events

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_events", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", 39000000, null, ["CrcV2_TransferSingle"], null, false, 100]}'

200

Array of events with event name and values payload (hex-encoded numerics).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "event": "CrcV2_TransferSingle",
      "values": {
        "blockNumber": "0x2c5da23",
        "timestamp": "0x6a213a3a",
        "transactionHash": "0x09be03621c385d8d7aaace7282c6f189bc82f87b8a6d3602fd5e76185fca1b38",
        "from": "0x42cedde51198d1773590311e2a340dc06b24cb37",
        "to": "0xf9117e9931e6ab91f025e1afa4e70cafa5e0aa1e",
        "operator": "0x5331b337ba0a9b0d1eb11b0832c3c8aed5b83b40",
        "id": "3348496524400290087352899048422089892780040790",
        "tokenAddress": "0x009626daded5e90aecee30ad3ebf2b3e510fe256",
        "value": "0x1d1a94a2000"
      }
    }
  ]
}

Generic table query

post

Runs a generic database query against an indexed namespace/table. Use circles_tables to discover available namespaces, tables and columns.

Positional params:

1. query (object, required) — A SelectDto:

   • Namespace (string) — e.g. V_Crc, CrcV2, CrcV2_ScoreGroup.

   • Table (string) — e.g. Avatars.

   • Columns (string[], optional) — Columns to return (empty = all).

   • Filter (object[], optional) — FilterPredicate objects ({ type, column, filterType, value }; filterType ∈ Equals, NotEquals, GreaterThan, LessThan, Like, In, IsNull, …).

   • Order (object[], optional) — [{ Column, SortOrder }], SortOrder ∈ ASC/DESC.

   • Limit (integer, optional), Distinct (boolean, optional).

2. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Result with columns and rows (rows are positional arrays aligned to columns).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_query

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_query", "params": [{"Namespace": "V_Crc", "Table": "Avatars", "Columns": [], "Filter": [], "Order": [], "Limit": 1}]}'

200

Result with columns and rows (rows are positional arrays aligned to columns).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "columns": [
      "blockNumber",
      "timestamp",
      "version",
      "type",
      "avatar",
      "tokenId"
    ],
    "rows": [
      [
        12541947,
        1602850860,
        1,
        "CrcV1_Signup",
        "0x9a0bbbbd3789f184ca88f2f6a40f42406cb842ac",
        "0x333d72f54cf17ba7a1971e7c7e9acb91c8b709d2"
      ]
    ]
  }
}

Paginated table query

post

Like circles_query but returns a { columns, rows, hasMore, nextCursor } wrapper for pagination.

Positional params:

1. query (object, required) — SelectDto (see circles_query).

2. cursor (string, optional) — Cursor from a previous response.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Paginated query result.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_paginated_query

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_paginated_query", "params": [{"Namespace": "V_Crc", "Table": "Avatars", "Limit": 1}]}'

200

Paginated query result.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "columns": [
      "blockNumber",
      "timestamp",
      "version",
      "type",
      "avatar",
      "tokenId"
    ],
    "rows": [
      [
        12541947,
        1602850860,
        1,
        "CrcV1_Signup",
        "0x9a0bbbbd3789f184ca88f2f6a40f42406cb842ac",
        "0x333d72f54cf17ba7a1971e7c7e9acb91c8b709d2"
      ]
    ],
    "hasMore": true,
    "nextCursor": "MTI1NDE5NDc6Mjoy"
  }
}

List available tables and schemas

post

Returns the catalog of available namespaces, tables, their event topics and column schemas.

Positional params: none.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of namespaces with their tables and column definitions.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_tables

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_tables", "params": []}'

200

Array of namespaces with their tables and column definitions.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "namespace": "CrcV1",
      "tables": [
        {
          "table": "Signup",
          "topic": "0x358ba8f768af134eb5af120e9a61dc1ef29b29f597f047b555fc3675064a0342",
          "columns": [
            {
              "column": "blockNumber",
              "type": "Int"
            },
            {
              "column": "timestamp",
              "type": "Int"
            },
            {
              "column": "user",
              "type": "Address"
            },
            {
              "column": "token",
              "type": "Address"
            }
          ]
        }
      ]
    }
  ]
}

Get complete profile view

post

Returns a complete profile view combining avatar info, profile, trust stats and balances.

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Combined profile view.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getProfileView

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getProfileView", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Combined profile view.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
    "avatarInfo": {
      "version": 2,
      "type": "CrcV2_RegisterHuman",
      "avatar": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
      "tokenId": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
      "hasV1": false,
      "isHuman": true,
      "cidV0": "QmY6WVuxFUVZ5zgm1D3b91JotnHDzis7S7pdwVQJ4sSXZy"
    },
    "profile": {
      "name": "martin",
      "@type": "Profile",
      "description": "yo"
    }
  }
}

Get trust network summary

post

Returns aggregated trust-network statistics for an address.

Positional params:

1. address (string, required) — Avatar address.

2. maxDepth (integer, optional) — Max depth for network traversal.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Trust network summary statistics.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTrustNetworkSummary

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTrustNetworkSummary", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Trust network summary statistics.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
    "directTrustsCount": 204,
    "directTrustedByCount": 254,
    "mutualTrustsCount": 117,
    "mutualTrusts": [
      "0x0142e59d7e0744e984aca46bbe9a7ef5c3fa50ba",
      "0x0180f81014d10543a6002e796d1f0ee5787e84cf"
    ]
  }
}

Get enriched aggregated trust relations

post

Trust relations categorized by type with enriched avatar info, paginated.

Positional params:

1. address (string, required) — Avatar address.

2. limit (integer, optional, default 50) — Max results per page.

3. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Enriched trust relations grouped under results.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getAggregatedTrustRelationsEnriched

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getAggregatedTrustRelationsEnriched", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", 50]}'

200

Enriched trust relations grouped under results.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
    "results": [
      {
        "address": "0x00177c523fb0243dc365a684b2ad48c9e2b4a758",
        "relationType": "trusts",
        "avatarInfo": {
          "version": 1,
          "type": "CrcV1_Signup",
          "avatar": "0x00177c523fb0243dc365a684b2ad48c9e2b4a758",
          "hasV1": true,
          "isHuman": true
        }
      }
    ]
  }
}

Get valid inviters

post

Returns addresses that trust the given address and have sufficient balance to invite.

Positional params:

1. address (string, required) — Avatar address.

2. minimumBalance (string, optional) — Minimum balance required (in CRC).

3. limit (integer, optional, default 50) — Max results.

4. cursor (string, optional) — Pagination cursor.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Valid inviters with balances and enriched avatar info.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getValidInviters

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getValidInviters", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", null, 50]}'

200

Valid inviters with balances and enriched avatar info.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
    "results": [
      {
        "address": "0x009626daded5e90aecee30ad3ebf2b3e510fe256",
        "balance": "6149.845019195272704375",
        "avatarInfo": {
          "version": 2,
          "type": "CrcV2_RegisterHuman",
          "isHuman": true,
          "cidV0": "QmSi8rVr1aGrGdKQFJ6hogariGvBXie6CrmxPHKrx9fiUo"
        }
      }
    ]
  }
}

Get invitation origin

post

Returns how a user joined Circles (the origin of their invitation).

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Invitation origin record.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getInvitationOrigin

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getInvitationOrigin", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Invitation origin record.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cedde51198d1773590311e2a340dc06b24cb37",
    "invitationType": "v2_standard",
    "blockNumber": 36531351,
    "timestamp": 1729067640,
    "transactionHash": "0x27a1cce27de9876f86066b709f9697e806560da0b6d88f64a08030c67851999c",
    "version": 2
  }
}

Get all invitations for an address

post

Returns all available invitations for an address from all sources (trust, escrow, at-scale).

Positional params:

1. address (string, required) — Avatar address.

2. minimumBalance (string, optional) — Minimum balance required (in CRC).

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Invitations grouped by source.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getAllInvitations

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getAllInvitations", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Invitations grouped by source.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
    "trustInvitations": [
      {
        "address": "0x009626daded5e90aecee30ad3ebf2b3e510fe256",
        "source": "trust",
        "balance": "6149.845019195272704375",
        "avatarInfo": {
          "version": 2,
          "type": "CrcV2_RegisterHuman",
          "isHuman": true
        }
      }
    ]
  }
}

Get trust-based invitations

post

Returns trust-based invitations (addresses that trust the target with sufficient balance).

Positional params:

1. address (string, required) — Avatar address.

2. minimumBalance (string, optional) — Minimum CRC balance required (in wei).

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of trust-based inviters (shape illustrative).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getTrustInvitations

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getTrustInvitations", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Array of trust-based inviters (shape illustrative).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0x009626daded5e90aecee30ad3ebf2b3e510fe256",
      "source": "trust",
      "balance": "6149.845019195272704375",
      "avatarInfo": {
        "version": 2,
        "type": "CrcV2_RegisterHuman",
        "isHuman": true
      }
    }
  ]
}

Get escrow-based invitations

post

Returns escrow-based invitations (CRC escrowed for the target address).

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of escrow invitations (shape illustrative).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getEscrowInvitations

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getEscrowInvitations", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Array of escrow invitations (shape illustrative).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0x009626daded5e90aecee30ad3ebf2b3e510fe256",
      "source": "escrow",
      "amount": "96000000000000000000"
    }
  ]
}

Get at-scale invitations

post

Returns at-scale invitations (pre-created unclaimed accounts) for an address.

Positional params:

1. address (string, required) — Avatar address.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Array of at-scale invitations (shape illustrative).

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getAtScaleInvitations

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getAtScaleInvitations", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37"]}'

200

Array of at-scale invitations (shape illustrative).

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0x009626daded5e90aecee30ad3ebf2b3e510fe256",
      "source": "atScale"
    }
  ]
}

Get accounts invited by an avatar

post

Returns accounts invited by a specific avatar (accepted or pending).

Positional params:

1. address (string, required) — Inviter avatar address.

2. accepted (boolean, optional, default false) — true = registered accounts, false = pending invitations.

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Invited accounts with status and enriched avatar info.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circles_getInvitationsFrom

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circles_getInvitationsFrom", "params": ["0x42cEDde51198D1773590311E2A340DC06B24cB37", true]}'

200

Invited accounts with status and enriched avatar info.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "address": "0x42cEDde51198D1773590311E2A340DC06B24cB37",
    "accepted": true,
    "results": [
      {
        "address": "0x467ca8cfa7d9953af39b89f8d381a47661d9d902",
        "status": "accepted",
        "blockNumber": 46412604,
        "timestamp": 1780003455,
        "avatarInfo": {
          "version": 2,
          "type": "CrcV2_RegisterHuman",
          "isHuman": true
        }
      }
    ]
  }
}

Find a transitive payment path

post

Calculates a transitive payment path through the trust network. Unlike most Circles methods, this takes a single object as the only params element.

params[0] object fields:

• source (string, required) — Source address.

• sink (string, required) — Destination address.

• targetFlow (string, required) — Target amount as a uint256 string (in wei). Use the max uint256 (115792089237316195423570985008687907853269984665640564039457584007913129639935) for a max-flow query.

• withWrap (boolean, optional) — Enable ERC20 wrapping.

• fromTokens / toTokens (string[], optional) — Whitelist source/destination tokens.

• excludedFromTokens / excludedToTokens (string[], optional) — Blacklist tokens.

• simulatedBalances (object[], optional) — Override balances for testing.

• simulatedTrusts (object[], optional) — Override trusts for testing.

• simulatedConsentedAvatars (string[], optional) — Pre-consented avatars.

• maxTransfers (integer, optional) — Max transfer hops.

• quantizedMode (boolean, optional) — 96 CRC quantization for invitations.

Routed to the Pathfinder, which shares the RPC root URL (/).

Body

JSON-RPC 2.0 request envelope. Sent via POST to the server root (/).

jsonrpcstring · enumRequired

JSON-RPC protocol version. Always "2.0".

Default: 2.0Possible values:

idone ofOptional

Request identifier echoed back in the response.

Default: 1

integerOptional

or

stringOptional

methodstringRequired

The RPC method name (also selects routing on the single root endpoint).

Responses

200

Computed flow with the ordered list of transfers.

application/json

JSON-RPC 2.0 response envelope. On success result is present; on failure error is present instead (still returned with HTTP 200).

jsonrpcstringOptionalExample: 2.0

idone ofOptionalExample: 1

integerOptional

or

stringOptional

resultanyOptional

Method-specific result. Present on success; see the example for each operation. (Type varies: string, object, array, boolean, …)

post/#circlesV2_findPath

curl -L -X POST 'https://rpc.aboutcircles.com/' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "circlesV2_findPath", "params": [{"source": "0x42cEDde51198D1773590311E2A340DC06B24cB37", "sink": "0x749c930256B47049cb65adFD39d8e3DD22A4d4Bd", "targetFlow": "1000000000000000000"}]}'

200

Computed flow with the ordered list of transfers.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "maxFlow": "0",
    "transfers": [],
    "graphBlock": 46522313
  }
}