Circles API Specifications

Get **v1** Circles total balance of an address

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getTotalBalance","params":["0xde374ece6fa50e781e81aac78e811b33d16912c7",true]}
and
Responses
200
Balance string
application/json
Responseall of
and
post
POST //circles_getTotalBalance HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getTotalBalance",
  "params": [
    "0xde374ece6fa50e781e81aac78e811b33d16912c7",
    true
  ]
}
200

Balance string

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

Get **v2** Circles total balance of an address

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circlesV2_getTotalBalance","params":["0xcadd4ea3bcc361fc4af2387937d7417be8d7dfc2",true]}
and
Responses
200
Balance string
application/json
Responseall of
and
post
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

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

Token-level balance breakdown (on-chain)

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getTokenBalances","params":["0xc6d075112b96b75460e543e3bf70be9ab45b62d9"]}
and
Responses
200
Array of token balances
application/json
post
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": [
    "0xc6d075112b96b75460e543e3bf70be9ab45b62d9"
  ]
}
200

Array of token balances

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

Fast indexed balance breakdown for an avatar

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getBalanceBreakdown","params":["0x14b31a052964143b4c455e3650164ff6c91f81be"]}
and
Responses
200
Balance map per token
application/json
post
POST //circles_getBalanceBreakdown HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getBalanceBreakdown",
  "params": [
    "0x14b31a052964143b4c455e3650164ff6c91f81be"
  ]
}
200

Balance map per token

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

List trust relations (in + out) for an avatar

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getTrustRelations","params":["0xde374ece6fa50e781e81aac78e811b33d16912c7"]}
and
Responses
200
Array of trust edges
application/json
post
POST //circles_getTrustRelations HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getTrustRelations",
  "params": [
    "0xde374ece6fa50e781e81aac78e811b33d16912c7"
  ]
}
200

Array of trust edges

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

Common outgoing trustees of two avatars

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getCommonTrust","params":["0xde374ece6fa50e781e81aac78e811b33d16912c7","0xe8fc7a2d0573e5164597b05f14fa9a7fca7b215c"]}
and
Responses
200
Intersection of trustees
application/json
post
POST //circles_getCommonTrust HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 159

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

Intersection of trustees

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

Path-finding with target flow (Circles v2)

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":0,"method":"circlesV2_findPath","params":[{"Source":"0x749c930256b47049cb65adcd7c25e72d5de44b3b","Sink":"0xde374ece6fa50e781e81aac78e811b33d16912c7","TargetFlow":"99999999999999999999999999999999999"}]}
and
Responses
200
Path with flow allocations
application/json
post
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": null
}

SQL-like indexed query

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_query","params":[{"Namespace":"V_CrcV2","Table":"TrustRelations","Columns":[],"Filter":[{"Type":"Conjunction","ConjunctionType":"Or","Predicates":[{"Type":"FilterPredicate","FilterType":"Equals","Column":"truster","Value":"0xae3a29a9ff24d0e936a5579bae5c4179c4dff565"},{"Type":"FilterPredicate","FilterType":"Equals","Column":"trustee","Value":"0xae3a29a9ff24d0e936a5579bae5c4179c4dff565"}]}],"Order":[]}]}
and
Responses
200
Tabular result set
application/json
post
POST //circles_query HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 447

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_query",
  "params": [
    {
      "Namespace": "V_CrcV2",
      "Table": "TrustRelations",
      "Columns": [],
      "Filter": [
        {
          "Type": "Conjunction",
          "ConjunctionType": "Or",
          "Predicates": [
            {
              "Type": "FilterPredicate",
              "FilterType": "Equals",
              "Column": "truster",
              "Value": "0xae3a29a9ff24d0e936a5579bae5c4179c4dff565"
            },
            {
              "Type": "FilterPredicate",
              "FilterType": "Equals",
              "Column": "trustee",
              "Value": "0xae3a29a9ff24d0e936a5579bae5c4179c4dff565"
            }
          ]
        }
      ],
      "Order": []
    }
  ]
}
200

Tabular result set

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

Stream / log event query

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_events","params":["0xde374ece6fa50e781e81aac78e811b33d16912c7",38000000,null,["CrcV1_Trust"],null,false]}
and
Responses
200
Array of event objects
application/json
post
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,
    [
      "CrcV1_Trust"
    ],
    null,
    false
  ]
}
200

Array of event objects

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

System health probe

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_health","params":[]}
and
Responses
200
Health status
application/json
post
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": null
}

List namespaces & tables

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":0,"method":"circles_tables","params":[]}
and
Responses
200
Namespace/table catalogue
application/json
post
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": null
}

Batch avatar metadata

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getAvatarInfoBatch","params":[["0xde374ece6fa50e781e81aac78e811b33d16912c7"]]}
and
Responses
200
Array of avatar objects
application/json
post
POST //circles_getAvatarInfoBatch HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getAvatarInfoBatch",
  "params": [
    [
      "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    ]
  ]
}
200

Array of avatar objects

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

Profile by CID

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getProfileByCid","params":["Qmb2s3hjxXXcFqWvDDSPCd1fXXa9gcFJd8bzdZNNAvk9W"]}
and
Responses
200
Profile data
application/json
post
POST //circles_getProfileByCid HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getProfileByCid",
  "params": [
    "Qmb2s3hjxXXcFqWvDDSPCd1fXXa9gcFJd8bzdZNNAvk9W"
  ]
}
200

Profile data

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

Profiles by CID (batch)

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getProfileByCidBatch","params":[["Qmb2s3hjxXXcFqWvDDSPCd1fXXa9gcFJd8bzdZNNAvk9W",null,"QmZuR1Jkhs9RLXVY28eTTRSnqbxLTBSoggp18Yde858xCM","QmanRNbDjbiSFdxcYT9S9wpk3gaCVnM81MVAHkmJj6AqE5"]]}
and
Responses
200
Array of profiles / nulls
application/json
post
POST //circles_getProfileByCidBatch HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getProfileByCidBatch",
  "params": [
    [
      "Qmb2s3hjxXXcFqWvDDSPCd1fXXa9gcFJd8bzdZNNAvk9W",
      null,
      "QmZuR1Jkhs9RLXVY28eTTRSnqbxLTBSoggp18Yde858xCM",
      "QmanRNbDjbiSFdxcYT9S9wpk3gaCVnM81MVAHkmJj6AqE5"
    ]
  ]
}
200

Array of profiles / nulls

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

Profile by avatar address

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getProfileByAddress","params":["0x5d033356cf431207ac72f3b48a86db0ebbcd6fdf"]}
and
Responses
200
Profile object or null
application/json
post
POST //circles_getProfileByAddress HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getProfileByAddress",
  "params": [
    "0x5d033356cf431207ac72f3b48a86db0ebbcd6fdf"
  ]
}
200

Profile object or null

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

Profiles by address (batch)

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getProfileByAddressBatch","params":[["0x5d033356cf431207ac72f3b48a86db0ebbcd6fdf","0x0e50fc4e7d629bc5edd69b6dddb3c22c6e60704b","0xf712d3b31de494b5c0ea51a6a407460ca66b12e8",null,"0xde374ece6fa50e781e81aac78e811b33d16912c7","0xde374ece6fa50e781e81aac78e811b33d16912c7"]]}
and
Responses
200
Array of profile objects / nulls
application/json
post
POST //circles_getProfileByAddressBatch HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 311

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_getProfileByAddressBatch",
  "params": [
    [
      "0x5d033356cf431207ac72f3b48a86db0ebbcd6fdf",
      "0x0e50fc4e7d629bc5edd69b6dddb3c22c6e60704b",
      "0xf712d3b31de494b5c0ea51a6a407460ca66b12e8",
      null,
      "0xde374ece6fa50e781e81aac78e811b33d16912c7",
      "0xde374ece6fa50e781e81aac78e811b33d16912c7"
    ]
  ]
}
200

Array of profile objects / nulls

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

Download full trust & balance snapshot

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_getNetworkSnapshot","params":[]}
and
Responses
200
Snapshot archive / manifest
application/json
post
POST //circles_getNetworkSnapshot HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 74

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

Snapshot archive / manifest

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

Text search over profiles

post
Body
all ofOptionalExample: {"jsonrpc":"2.0","id":1,"method":"circles_searchProfiles","params":["Ben",10,0]}
and
Responses
200
Paged profile search hits
application/json
post
POST //circles_searchProfiles HTTP/1.1
Host: rpc.aboutcircles.com
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "circles_searchProfiles",
  "params": [
    "Ben",
    10,
    0
  ]
}
200

Paged profile search hits

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
PreviousSetting up Circles SDK with ReactNextQuery Circles Data

Last updated

Was this helpful?