Circles API

Get v2 Circles total balance of an address

post

Body

and

Responses

200

Balance string (decimal or integer depending on asTimeCircles).

application/json

post

/circlesV2_getTotalBalance

POST /circlesV2_getTotalBalance HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 122

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circlesV2_getTotalBalance",
  "params": [
    "0xcadd4ea3bcc361fc4af2387937d7417be8d7dfc2",
    true
  ]
}

200

Balance string (decimal or integer depending on asTimeCircles).

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

Get all Circles v2 token balances held by an address

post

Body

and

Responses

200

Array of token balances.

application/json

post

/circles_getTokenBalances

POST /circles_getTokenBalances HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getTokenBalances",
  "params": [
    "0xd68193591d47740e51dfbc410da607a351b56586"
  ]
}

200

Array of token balances.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "TokenAddress": "text",
      "TokenId": "text",
      "TokenOwner": "text",
      "TokenType": "CrcV2_RegisterHuman",
      "Version": 2,
      "AttoCircles": "99999999999999999999999999999999999",
      "Circles": 1,
      "StaticAttoCircles": "99999999999999999999999999999999999",
      "StaticCircles": 1,
      "AttoCrc": "99999999999999999999999999999999999",
      "Crc": 1,
      "IsErc20": true,
      "IsErc1155": true,
      "IsWrapped": true,
      "IsInflationary": true,
      "IsGroup": true
    }
  ]
}

Get common trust between two addresses (v2)

post

Body

and

Responses

200

Array of common trusted addresses.

application/json

post

/circles_getCommonTrust

POST /circles_getCommonTrust HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 161

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getCommonTrust",
  "params": [
    "0xde374ece6fa50e781e81aac78e811b33d16912c7",
    "0xae3a29a9ff24d0e936a5579bae5c4179c4dff565",
    2
  ]
}

200

Array of common trusted addresses.

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

Path-finding with target flow (Circles v2)

post

Body

and

Responses

200

Path with flow allocations.

application/json

post

/circlesV2_findPath

POST /circlesV2_findPath HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "circlesV2_findPath",
  "params": [
    {
      "Source": "0x749c930256b47049cb65adcd7c25e72d5de44b3b",
      "Sink": "0xde374ece6fa50e781e81aac78e811b33d16912c7",
      "TargetFlow": "99999999999999999999999999999999999"
    }
  ]
}

200

Path with flow allocations.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "MaxFlow": "99999999999999999999999999999999999",
    "Transfers": [
      {
        "From": "text",
        "To": "text",
        "TokenOwner": "text",
        "Value": "99999999999999999999999999999999999"
      }
    ]
  }
}

SQL-like indexed query

post

Perform a SQL-like query on the indexed data.

Useful query templates (YAML)

Recent v2 avatar registrations

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "Avatars"
    Columns:
      - "blockNumber"
      - "timestamp"
      - "transactionHash"
      - "type"
      - "avatar"
      - "tokenId"
      - "name"
      - "cidV0Digest"
    Filter:
      []
    Order:
      -
        Column: "blockNumber"
        SortOrder: "DESC"
      -
        Column: "transactionIndex"
        SortOrder: "DESC"
      -
        Column: "logIndex"
        SortOrder: "DESC"
    Limit: 25

Incoming + outgoing trust relations for an address

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "TrustRelations"
    Columns:
      - "blockNumber"
      - "timestamp"
      - "truster"
      - "trustee"
      - "expiryTime"
    Filter:
      -
        Type: "Conjunction"
        ConjunctionType: "Or"
        Predicates:
          -
            Type: "FilterPredicate"
            FilterType: "Equals"
            Column: "truster"
            Value: "0xae3a29a9ff24d0e936a5579bae5c4179c4dff565"
          -
            Type: "FilterPredicate"
            FilterType: "Equals"
            Column: "trustee"
            Value: "0xae3a29a9ff24d0e936a5579bae5c4179c4dff565"
    Order:
      -
        Column: "blockNumber"
        SortOrder: "DESC"
      -
        Column: "logIndex"
        SortOrder: "DESC"

Balances for one account, ordered by demurraged balance

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "BalancesByAccountAndToken"
    Columns:
      - "account"
      - "tokenAddress"
      - "tokenId"
      - "lastActivity"
      - "totalBalance"
      - "demurragedTotalBalance"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "account"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "demurragedTotalBalance"
        SortOrder: "DESC"
    Limit: 50

Group overview with membership counts

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "Groups"
    Columns:
      - "group"
      - "name"
      - "symbol"
      - "memberCount"
      - "owner"
      - "mintPolicy"
      - "treasury"
      - "erc20WrapperDemurraged"
      - "erc20WrapperStatic"
    Filter:
      []
    Order:
      -
        Column: "memberCount"
        SortOrder: "DESC"
    Limit: 20

Members of a group (v2)

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupMemberships"
    Columns:
      - "group"
      - "member"
      - "memberType"
      - "expiryTime"
      - "timestamp"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"

Recent transfers involving an address

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "Transfers"
    Columns:
      - "blockNumber"
      - "timestamp"
      - "transactionHash"
      - "from"
      - "to"
      - "id"
      - "value"
      - "type"
    Filter:
      -
        Type: "Conjunction"
        ConjunctionType: "Or"
        Predicates:
          -
            Type: "FilterPredicate"
            FilterType: "Equals"
            Column: "from"
            Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
          -
            Type: "FilterPredicate"
            FilterType: "Equals"
            Column: "to"
            Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "blockNumber"
        SortOrder: "DESC"
      -
        Column: "transactionIndex"
        SortOrder: "DESC"
      -
        Column: "logIndex"
        SortOrder: "DESC"
    Limit: 100

Total supply for a specific token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "TotalSupply"
    Columns:
      - "tokenAddress"
      - "tokenId"
      - "totalSupply"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "tokenAddress"
        Value: "0x42cedde51198d1773590311e2a340dc06b24cb37"
    Order:
      []

Holders of a group token with ownership fraction

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupTokenHoldersBalance"
    Columns:
      - "group"
      - "holder"
      - "demurragedTotalBalance"
      - "fractionOwnership"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "demurragedTotalBalance"
        SortOrder: "DESC"
    Limit: 50

Group token supply (demurraged)

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupTokenSupply"
    Columns:
      - "group"
      - "totalSupply"
      - "demurragedTotalSupply"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      []

Group collateral locked by token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupCollateralByToken"
    Columns:
      - "group"
      - "id"
      - "amountLocked"
      - "demurragedAmountLocked"
      - "fractionLocked"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "amountLocked"
        SortOrder: "DESC"

Group vault balances by token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupVaultBalancesByToken"
    Columns:
      - "vault"
      - "id"
      - "balance"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "vault"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "balance"
        SortOrder: "DESC"

Daily group member counts

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupMembersCount_1d"
    Columns:
      - "group"
      - "timestamp"
      - "value"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 30

Daily wrap/unwrap activity for a group token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupWrapUnWrap_1d"
    Columns:
      - "group"
      - "timestamp"
      - "tokenAddress"
      - "tokenType"
      - "wrapAmount"
      - "unwrapAmount"
      - "wrapSupply"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 30

Daily mint/redeem activity for a group token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupMintRedeem_1d"
    Columns:
      - "group"
      - "timestamp"
      - "minted"
      - "burned"
      - "supply"
      - "demurragedMinted"
      - "demurragedBurned"
      - "demurragedSupply"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 30

Daily affiliate members count

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "AffiliateMembersCount_1d"
    Columns:
      - "group"
      - "timestamp"
      - "value"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 30

Daily Balancer vault balance for an ERC20 wrapper

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "Erc20BalancerVaultBalance_1d"
    Columns:
      - "timestamp"
      - "tokenAddress"
      - "value"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "tokenAddress"
        Value: "0x42cedde51198d1773590311e2a340dc06b24cb37"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 30

LBP circles backing deployments

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "CrcV2"
    Table: "CirclesBackingDeployed"
    Columns:
      - "blockNumber"
      - "timestamp"
      - "transactionHash"
      - "emitter"
      - "backer"
      - "circlesBackingInstance"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "backer"
        Value: "0xeced91232c609a42f6016860e8223b8aecaa7bd0"
    Order:
      -
        Column: "blockNumber"
        SortOrder: "DESC"
    Limit: 100

Group collateral delta by token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupCollateralDiffByToken"
    Columns:
      - "timestamp"
      - "group"
      - "id"
      - "amountLocked"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 100

Hourly group member counts

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupMembersCount_1h"
    Columns:
      - "group"
      - "timestamp"
      - "value"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 72

Hourly wrap/unwrap activity for a group token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupWrapUnWrap_1h"
    Columns:
      - "group"
      - "timestamp"
      - "tokenAddress"
      - "tokenType"
      - "wrapAmount"
      - "unwrapAmount"
      - "wrapSupply"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 72

Hourly mint/redeem activity for a group token

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "GroupMintRedeem_1h"
    Columns:
      - "group"
      - "timestamp"
      - "minted"
      - "burned"
      - "supply"
      - "demurragedMinted"
      - "demurragedBurned"
      - "demurragedSupply"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 72

Hourly affiliate members count

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "AffiliateMembersCount_1h"
    Columns:
      - "group"
      - "timestamp"
      - "value"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "group"
        Value: "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 72

Hourly Balancer vault balance for an ERC20 wrapper

jsonrpc: "2.0"
id: 1
method: "circles_query"
params:
  -
    Namespace: "V_CrcV2"
    Table: "Erc20BalancerVaultBalance_1h"
    Columns:
      - "timestamp"
      - "tokenAddress"
      - "value"
    Filter:
      -
        Type: "FilterPredicate"
        FilterType: "Equals"
        Column: "tokenAddress"
        Value: "0x42cedde51198d1773590311e2a340dc06b24cb37"
    Order:
      -
        Column: "timestamp"
        SortOrder: "DESC"
    Limit: 72

Body

and

Responses

200

Tabular result set.

application/json

post

/circles_query

POST /circles_query HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 372

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_query",
  "params": [
    {
      "Namespace": "V_CrcV2",
      "Table": "Avatars",
      "Columns": [
        "blockNumber",
        "timestamp",
        "transactionHash",
        "type",
        "avatar",
        "tokenId",
        "name",
        "cidV0Digest"
      ],
      "Filter": [],
      "Order": [
        {
          "Column": "blockNumber",
          "SortOrder": "DESC"
        },
        {
          "Column": "transactionIndex",
          "SortOrder": "DESC"
        },
        {
          "Column": "logIndex",
          "SortOrder": "DESC"
        }
      ],
      "Limit": 25
    }
  ]
}

200

Tabular result set.

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

Stream / log event query

post

Body

and

Responses

200

Array of event objects.

application/json

post

/circles_events

POST /circles_events HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 147

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_events",
  "params": [
    "0xde374ece6fa50e781e81aac78e811b33d16912c7",
    38000000,
    null,
    [
      "CrcV2_Trust"
    ],
    null,
    false
  ]
}

200

Array of event objects.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "Event": "text",
      "Values": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ]
}

System health probe

post

Body

and

Responses

200

Health status.

application/json

post

/circles_health

POST /circles_health HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_health",
  "params": []
}

200

Health status.

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

List namespaces, tables, and columns

post

Body

and

Responses

200

Namespace/table catalogue.

application/json

post

/circles_tables

POST /circles_tables HTTP/1.1
Host: rpc.aboutcircles.com/
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "circles_tables",
  "params": []
}

200

Namespace/table catalogue.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "Namespace": "text",
      "Tables": [
        {
          "Table": "text",
          "Topic": "text",
          "Columns": [
            {
              "Column": "text",
              "Type": "text"
            }
          ]
        }
      ]
    }
  ]
}

Last updated 1 month ago

Was this helpful?

hashtagGet v2 Circles total balance of an address

hashtagGet all Circles v2 token balances held by an address

hashtagGet common trust between two addresses (v2)

hashtagPath-finding with target flow (Circles v2)

hashtagSQL-like indexed query

hashtagRecent v2 avatar registrations

hashtagIncoming + outgoing trust relations for an address

hashtagBalances for one account, ordered by demurraged balance

hashtagGroup overview with membership counts

hashtagMembers of a group (v2)

hashtagRecent transfers involving an address

hashtagTotal supply for a specific token

hashtagHolders of a group token with ownership fraction

hashtagGroup token supply (demurraged)

hashtagGroup collateral locked by token

hashtagGroup vault balances by token

hashtagDaily group member counts

hashtagDaily wrap/unwrap activity for a group token

hashtagDaily mint/redeem activity for a group token

hashtagDaily affiliate members count

hashtagDaily Balancer vault balance for an ERC20 wrapper

hashtagLBP circles backing deployments

hashtagGroup collateral delta by token

hashtagHourly group member counts

hashtagHourly wrap/unwrap activity for a group token

hashtagHourly mint/redeem activity for a group token

hashtagHourly affiliate members count

hashtagHourly Balancer vault balance for an ERC20 wrapper

hashtagStream / log event query

hashtagSystem health probe

hashtagList namespaces, tables, and columns

Get v2 Circles total balance of an address

Get all Circles v2 token balances held by an address

Get common trust between two addresses (v2)

Path-finding with target flow (Circles v2)

SQL-like indexed query

Recent v2 avatar registrations

Incoming + outgoing trust relations for an address

Balances for one account, ordered by demurraged balance

Group overview with membership counts

Members of a group (v2)

Recent transfers involving an address

Total supply for a specific token

Holders of a group token with ownership fraction

Group token supply (demurraged)

Group collateral locked by token

Group vault balances by token

Daily group member counts

Daily wrap/unwrap activity for a group token

Daily mint/redeem activity for a group token

Daily affiliate members count

Daily Balancer vault balance for an ERC20 wrapper

LBP circles backing deployments

Group collateral delta by token

Hourly group member counts

Hourly wrap/unwrap activity for a group token

Hourly mint/redeem activity for a group token

Hourly affiliate members count

Hourly Balancer vault balance for an ERC20 wrapper

Stream / log event query

System health probe

List namespaces, tables, and columns