--- updatedAt: 2026-08-31T17:41:20.000Z --- Fetch the complete documentation index at: https://docs.skyfire.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # Introspect Token Check whether a token is currently usable and get the remaining balance as a buyer or seller agent. This endpoint always returns `200`, even when the token is invalid, check `isValid` in the body. A `401` response means the API key itself was rejected, not the token. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "skyfire-agent-and-token-apis", "version": "1.0" }, "servers": [ { "url": "https://api.skyfire.xyz" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "skyfire-api-key", "in": "header" } } }, "security": [ { "sec0": [] } ], "paths": { "/api/v1/tokens/introspect": { "post": { "summary": "Introspect Token", "description": "Check whether a token is currently usable and get the remaining balance as a buyer or seller agent.", "operationId": "introspect-token", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The complete JWT string as issued to the buyer, not a `tokenId`. Can be of any token type: `kya`, `pay`, or `kya-pay`." } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Invalid token": { "summary": "Invalid token", "value": { "isValid": false, "validationError": "invalid or expired jwt" } }, "Valid pay/kya-pay token": { "summary": "Valid pay/kya-pay token", "value": { "chargeableUntil": 1774036197.827, "expiresAt": 1773949797.827, "isValid": true, "remainingBalance": "0.001" } }, "Valid kya token": { "value": { "expiresAt": 1773952576.644, "isValid": true }, "summary": "Valid kya token" } }, "schema": { "oneOf": [ { "type": "object", "properties": { "expiresAt": { "type": "number", "description": "Unix timestamp (seconds) after which the token expires; the token's `exp` claim." }, "isValid": { "type": "boolean", "description": "Whether the token passed introspection. `true` for up to 24 hours past `expiresAt` (settlement grace period)." }, "validationError": { "type": "string", "description": "Present only when `isValid: false`. Human-readable, not a stable error code. Cases include: unparseable JWT, unknown token id, bad signature, past hold expiry, caller not a party to the token, malformed claims (`aud`/`sub`/`ssi`/`typ`), seller service inactive or unapproved, missing external seller or merchant account, wallet/address/network mismatch, balance-lookup failure. Unrecognized errors fall back to `Token is invalid or not found`." } }, "required": [ "expiresAt", "isValid" ], "title": "kya tokens" }, { "type": "object", "properties": { "chargeableUntil": { "type": "number", "description": "Unix timestamp (seconds) after which the token can no longer be charged." }, "expiresAt": { "type": "number", "description": "Unix timestamp (seconds) after which the token expires; the token's `exp` claim." }, "isValid": { "type": "boolean", "description": "Whether the token passed introspection. `true` until `chargeableUntil`." }, "remainingBalance": { "type": "string", "description": "Funds left on the token as a decimal string." }, "validationError": { "type": "string", "description": "Present only when `isValid: false`. Human-readable, not a stable error code. Cases include: unparseable JWT, unknown token id, bad signature, past hold expiry, caller not a party to the token, malformed claims (`aud`/`sub`/`ssi`/`typ`), seller service inactive or unapproved, missing external seller or merchant account, wallet/address/network mismatch, balance-lookup failure. Unrecognized errors fall back to `Token is invalid or not found`." } }, "required": [ "chargeableUntil", "expiresAt", "isValid", "remainingBalance" ], "title": "pay, kya-pay tokens" } ] } } } } }, "x-readme": { "code-samples": [ { "language": "curl", "code": "curl -X POST 'https://api.skyfire.xyz/api/v1/tokens/introspect' \\\n-H 'skyfire-api-key: 1fd8543f-0fc6-4f80-9b6e-09f9eecbbdf5' \\\n-H 'Content-Type: application/json'\n-d '{\n \"token\": \"eyJhbGciOiJFUzI1NiIsImtpZCI6IjAiLCJ0eXAiOiJwYXkrSldUIa9.eyJlbnYiOiJwcm9kdWN0aW9uIiwiYnRnIjoiUGxheWdyb3VuZC02anlqbzNrejZoNiIsInNzaSI6IjIyM2JjM2ViLTliY2ItNGU5Yi1hZmQ2LWYyNmVlMGJkMzg5NCIsInZhbHVlIjoiNTAwMCIsImFtb3VudCI6IjAuMDA1Iiwic3BzIjoiUEFZX1BFUl9VU0UiLCJzcHIiOiIwLjAwMDAwMSIsIm1uciI6NTAwMCwiY3VyIjoiVVNEIiwiaWF0IjoxNzUzNDY2MDMzLCJpc3MiOiJodHRwczovL2FwcC5za3lmaXJlLnh5eiIsImp0aSI6IjBmYWZjYzllLTdjNDMtNGJkMS1iYzVmLWRkYjkwNjNjODExNCIsImF1ZCI6IjVlMDE0NTg2LTExYWYtNDhmNC05NGU3LTdhZDE1Yjk3ZmFlNyIsInN1YiI6ImE0YzA5ZWVlLThjZTgtNGNkYy1iNzFjLTdjNDFhOTA0YTEyNCIsImV4cCI6MTc1MzQ2NjMzMH0.vIu14Ic8RraiWkksHZas0LqWIib4ZIUdvySSS5dtsFrnHajBdZvQm3pC6ocG4p3CxHufhTISgE4_NG9nQRWCrQ\"\n}'" }, { "language": "node", "code": "var https = require('follow-redirects').https;\nvar fs = require('fs');\n\nvar options = {\n 'method': 'POST',\n 'hostname': 'api.skyfire.xyz',\n 'path': '/api/v1/tokens/introspect',\n 'headers': {\n 'skyfire-api-key': '1fd8543f-0fc6-4f80-9b6e-09f9eecbbdf5',\n 'Content-Type': 'application/json'\n },\n 'maxRedirects': 20\n};\n\nvar req = https.request(options, function (res) {\n var chunks = [];\n\n res.on(\"data\", function (chunk) {\n chunks.push(chunk);\n });\n\n res.on(\"end\", function (chunk) {\n var body = Buffer.concat(chunks);\n console.log(body.toString());\n });\n\n res.on(\"error\", function (error) {\n console.error(error);\n });\n});\n\nvar postData = JSON.stringify({\n \"token\": \"eyJhbGciOiJFUzI1NiIsImtpZCI6IjAiLCJ0eXAiOiJwYXkrSldUIa9.eyJlbnYiOiJwcm9kdWN0aW9uIiwiYnRnIjoiUGxheWdyb3VuZC02anlqbzNrejZoNiIsInNzaSI6IjIyM2JjM2ViLTliY2ItNGU5Yi1hZmQ2LWYyNmVlMGJkMzg5NCIsInZhbHVlIjoiNTAwMCIsImFtb3VudCI6IjAuMDA1Iiwic3BzIjoiUEFZX1BFUl9VU0UiLCJzcHIiOiIwLjAwMDAwMSIsIm1uciI6NTAwMCwiY3VyIjoiVVNEIiwiaWF0IjoxNzUzNDY2MDMzLCJpc3MiOiJodHRwczovL2FwcC5za3lmaXJlLnh5eiIsImp0aSI6IjBmYWZjYzllLTdjNDMtNGJkMS1iYzVmLWRkYjkwNjNjODExNCIsImF1ZCI6IjVlMDE0NTg2LTExYWYtNDhmNC05NGU3LTdhZDE1Yjk3ZmFlNyIsInN1YiI6ImE0YzA5ZWVlLThjZTgtNGNkYy1iNzFjLTdjNDFhOTA0YTEyNCIsImV4cCI6MTc1MzQ2NjMzMH0.vIu14Ic8RraiWkksHZas0LqWIib4ZIUdvySSS5dtsFrnHajBdZvQm3pC6ocG4p3CxHufhTISgE4_NG9nQRWCrQ\"\n});\n\nreq.write(postData);\n\nreq.end();" }, { "language": "python", "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"api.skyfire.xyz\")\npayload = json.dumps({\n \"token\": \"eyJhbGciOiJFUzI1NiIsImtpZCI6IjAiLCJ0eXAiOiJwYXkrSldUIa9.eyJlbnYiOiJwcm9kdWN0aW9uIiwiYnRnIjoiUGxheWdyb3VuZC02anlqbzNrejZoNiIsInNzaSI6IjIyM2JjM2ViLTliY2ItNGU5Yi1hZmQ2LWYyNmVlMGJkMzg5NCIsInZhbHVlIjoiNTAwMCIsImFtb3VudCI6IjAuMDA1Iiwic3BzIjoiUEFZX1BFUl9VU0UiLCJzcHIiOiIwLjAwMDAwMSIsIm1uciI6NTAwMCwiY3VyIjoiVVNEIiwiaWF0IjoxNzUzNDY2MDMzLCJpc3MiOiJodHRwczovL2FwcC5za3lmaXJlLnh5eiIsImp0aSI6IjBmYWZjYzllLTdjNDMtNGJkMS1iYzVmLWRkYjkwNjNjODExNCIsImF1ZCI6IjVlMDE0NTg2LTExYWYtNDhmNC05NGU3LTdhZDE1Yjk3ZmFlNyIsInN1YiI6ImE0YzA5ZWVlLThjZTgtNGNkYy1iNzFjLTdjNDFhOTA0YTEyNCIsImV4cCI6MTc1MzQ2NjMzMH0.vIu14Ic8RraiWkksHZas0LqWIib4ZIUdvySSS5dtsFrnHajBdZvQm3pC6ocG4p3CxHufhTISgE4_NG9nQRWCrQ\"\n})\nheaders = {\n 'skyfire-api-key': '1fd8543f-0fc6-4f80-9b6e-09f9eecbbdf5',\n 'Content-Type': 'application/json'\n}\nconn.request(\"POST\", \"/api/v1/tokens/introspect\", payload, headers)\nres = conn.getresponse()\ndata = res.read()\nprint(data.decode(\"utf-8\"))" } ], "samples-languages": [ "curl", "node", "python" ] } } } }, "x-readme": { "headers": [ { "key": "skyfire-api-key", "value": "" } ], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```