https://ons.sessionbots.directory/ API docs

ons.sessionbots.directory api docs.md

[16th February 2024]

API reference for ons.sessionbots.directory:

• No Authorization required
• No rate limits other than Cloudflare's
• Data is fetched directly from local SQL databse
• HTTPS-only (with http->https 301 redirect)
• Always returns either JSON (from API) or HTML (from Cloudflare)
• Base URL is https://ons.sessionbots.directory/api/
• Always returns {"ok":true} with other properties or {"ok":false,"error":"string"}

Resolve single ONS name

Also automatically caches that unhashed lookup for future calls

GET https://ons.sessionbots.directory/api/session/:name

Example response: (HTTP status 200)

{
  "ok": true,
  "mappings": [
    {
      "name": "name",
      "owner": {
        "keypair": "a0854d8f434741a4a8b933baaff2215d964baeef70ae1df21545d1ed9741e1e4aeb5bc00e7d225859fa8db58c96fc73e1a06718bb3fd5b11ed63648f4ce77caa00000000000000000000000000000000",
        "oxen": "LB2VrNk37EQUYQAEfXtoi8Geuu4Xs5DrLhVWYEBvPgjafFWNHPrW3JkPMKPLii1a1tBPTuZnHi1X83zvCcgrTHx7LFDhGUi"
      },
      "backupOwner": {"keypair": null, "oxen": null},
      "sessionId": "05e241803c4fb0af448dc2261c88ec00dca0783f3d25465e4025d8c11a579edd5d",
      "transactionId": "a17a9885c031d8dd1ffa861e976d6f988fb28f6c26370f900c67c69a4d22a285",
      "updatedAtBlock": 1251206,
      "expiresAtBlock": null,
      "action": null
    }
  ]
}

Get all known ONS for SessionID

This endpoint can't guarantee returning ALL ONS for this particular Session ID. This is because by nature ONS and their SessionIDs are hidden in blockchain and stored as hash. This endpoint even has no way of getting the total number of ONS belonging to user, so it will only return KNOWN ONS.

GET https://ons.sessionbots.directory/api/sessionid/:sessionid

Example response: (HTTP status 200)

{"ok":true,"names":["hloth"]}

Fetch list of ONS mappings

GET https://ons.sessionbots.directory/api/list

Query arguments:

• "query" (optional, string, min: 1, max: 64, regex: only allowed ONS characters, default: empty) — Search query
• "type" (optional, string with commas representing array of enums, enum: "session", "wallet", "lokinet", default: "session", example: "session,wallet,lokinet") — Type of ons names to return
• "max_block" (optional, integer, positive) — Max # of block from which to return ons names
• "min_block" (optional, integer, positive) — Min # of block from which to return ons names
• "limit" (optional, either integer, positive or enum: "all") — Max number of ons names to return in "mappings" array
• "sort_by" (optional, enum: "updatedAtBlock", default: "DESC") — Sorting property
• "sort_dir" (optional, enum: "ASC", "DESC", default: "DESC") — Sorting direction, either ascending or descending
• "owner" (optional, string, min: 1, max: 160) — Filter by owner
• "value" (optional, string, min: 1) — Filter by decrypted value, e.g. Session ID
• "offset" (optional, number, integer, min: 0) — Skip specified number of search results

Example response: (HTTP status 200):

{
  "ok": true,
  "mappings": [
    {
      "name": null,
      "nameHash": "dT8uq+PZaUOP7T02pJfhudY5laH/K/sLfxad3GXQUMk=",
      "owner": {
        "keypair": "LD7c7bt5E3BJmXp7c1JZwpcXdGftLrNHnbAP3fY7RpgEVZVWfCGgq5yWDiszRcgvQsayyd5sWzGFB8UwnFZjAbjtC7hcKFt",
        "oxen": "d79f1337db0c626a3a038d080a8f73d4687e009adf8779cc3d57619a8a5d7faac01223464bcfc8aeb0e8f023b27064cb2accfc42612e4a2cbb13a43b940c876200000000000000000000000000000000"
      },
      "backupOwner": {"keypair": null, "oxen": null},
      "sessionId": null,
      "sessionIdEncrypted": "d32bba3de36cb6e7135db3a5cfc1b7d0db5eb2b355c4da80ea196b22cbb124db3fe095bce1514548f8e016308b82b902ef268f3cd9ea66ebe2fd668530878dac5ee8b7a39779a0c3b8",
      "transactionId": "78596681859d71e2e1c809b8bfd5de06f090a39dc0b7ed9adf3ddac2b0d0ef7d",
      "updatedAtBlock": 1519688,
      "expiresAtBlock": null,
      "action": "buy"
    },
    {
      "name": null,
      "nameHash": "AT9MSezrazMebL5ArWdxoJY6d4WX0YEUml79De0uawc=",
      "owner": {
        "keypair": "L5kK5pp6xvFQtup4r6QiKj1h5PJ9FnTubhrrCBJtRLcEgnLmVc5QkWHYZeTvxsWLjfCLLTN811mJuc7pdgQwcEFJBeattaq",
        "oxen": "153708d68114e48edbe2a17395bbca042187507d2b43baf4485ec0bd081c37edd6e7aa6ce89c66bcb3b7583746499e43c1fe69f7923eded1f45766a338d9095e00000000000000000000000000000000"
      },
      "backupOwner": {"keypair": null, "oxen": null},
      "sessionId": null,
      "sessionIdEncrypted": "e71b9f7e1135fc280b4a66d360f8e62d4da4c1d854f61f2c84dfcdfaa6f0ce5cd00911c6ce6c5e8114f350aba305040e610bab6465c317a7279e3d3ed8e0a4a14b6200e25bacf530fa",
      "transactionId": "75398333733ff1a238dbb4aa7c137ee3c8b32771ce2b25eb0c69721ea2c1e754",
      "updatedAtBlock": 1518521,
      "expiresAtBlock": null,
      "action": "buy"
    }
  ],
  "total": 5113
}

Get ONS share grouped by wallet

GET https://ons.sessionbots.directory/api/share

Example response (HTTP status 200):

{
  "ok": true,
  "shares": [
    [
      "L7TjJeeaKsSAEcj5KFX6kz7kQ1V6wWyidRDwYbf2qL4bci5fdKeGnDJR2XRGs2m1WNAyYN2baWK89RM1o1MH51x4KakvrJX",
      603
    ],
    [
      "LCxMvBRVj2XfkyZGDjjpQraRnMq5B97aB3b7uLMQyA6tJ62M6PU36V1HLDpgZfCcmbUFTBNajXJw9CpXemAt3WtUJrEWScH",
      417
    ],
    [
      "L6ygQVHjH7w1jEHAxVyTzq5CLyWHs2v53dXnpDBXWQyAKQuJ414qRnw3goK4odKC2tJMpkonjnx8rDG2tD3px1V3LWBVUG5",
      397
    ],
    [
      "LAgwKQKm25RYdmgrF8CrVNb69oettuVnuUKvYWFLUFcNL7Yn1qTZaKRYTZweKA2sFsHKCgiWHDUt95qBnppFyr5XUduBnwJ",
      316
    ],
    [
      "LEXeB1DTcMJTKSDLkjMBmA5V38EjdXV7T1x9qDayAei9UVCUbirjT7HEwAebLgd9WTRQjEnHhhJFTHJ5e7NrzpU1BNe4TEi",
      229
    ],
    [
      "L7dRJGp2rvXAm5J25Mp2fo1xkeC94bq2jEF7PfS4GGiqWQu2XPDGS7tTmKaxQzzQFk62BXQ6a7fGK8NPt7tB6fJnUFC2XBQ",
      199
    ],
    [
      "L6YiQsK6PMDdrzsZHumt5x7fVZuniaxAsPp45HzUehfDeh1vsiMJQddB2D3feY7jSF8cRyZBXseq5WtdG25zm7gZ1jPeL84",
      199
    ],
    [
      "LDvt3RC5HLGTWZXswtegkF24HgwUmHTJfcctviVD1wJECSSJwC1YyWT3THKUA8BmkWSpy7hMJaXLF5LwbL3BtBS4Gg4jZVf",
      135
    ],
    [
      "L8caUrwd1ss3soUao1Mxi3FAvu7JFCHvh6cs7WvbyPuPAPifyAFGZimK3sc4FrTAY2hKTxeAaMX8TWJn7YY54naGFwWpt74",
      124
    ]
  ]
}

Follow our Session channel for more info:

https://sogs.hloth.dev/ons-registry?public_key=8948f2d9046a40e7dbc0a4fd7c29d8a4fe97df1fa69e64f0ab6fc317afb9c945