{ "openapi": "3.1.0", "info": { "title": "Plug API", "description": "Programmable Ethereum transactions without smart contracts. A single framework to manage your crypto holdings, compose your protocol interactions, and schedule and run complex transactions.", "version": "0.1.0", "termsOfService": "https://plug.to/terms/" }, "servers": [ { "url": "https://api.plug.to" } ], "tags": [ { "name": "Address", "description": "Read any EVM address without a key or a wallet connection: metadata and graph signals, every indexed fungible, non-fungible and non-tokenized position, transaction history, and portfolio value over time." }, { "name": "Transaction", "description": "Compose, compile and submit intents. Resolve the inputs an action accepts, build calldata from structured inputs, preview a draft sequence without persisting it, then broadcast or cancel." }, { "name": "Chain", "description": "Configuration and metadata for every blockchain network Plug indexes and executes on." }, { "name": "Authentication", "description": "Sign in with Ethereum. Issue a nonce, exchange a signed SIWE message for a token pair, and rotate it. Only writes bound to a wallet need this — every read surface is open." }, { "name": "CDN", "description": "Derived presentation data for remote assets, such as the dominant color of a hosted image." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [], "paths": { "/address/{address}/": { "get": { "operationId": "getAddress", "summary": "Get address", "description": "Returns everything Plug knows about an address at the identity level: its metadata and the signal flags the indexing graph has raised on it.\n\nThe response is the address as the indexer sees it, not as a wallet does. Graph signals classify what the address is (a contract, a token, a router, a known entity) and how it behaves, derived from indexed history rather than a registry someone maintains by hand. Requesting an address that has never been seen queues it for indexing immediately, so a cold address warms up by being asked about.\n\nReach for it as the first call in any flow that starts from a raw address: resolving what something is before deciding which of the other surfaces to read next.", "tags": [ "Address" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } } ], "responses": { "200": { "description": "Get address", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "object", "null" ], "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "token_id": { "type": "string" }, "standard": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "icon": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "attributes": { "description": "Arbitrarily nested map holding everything indexed about this entry beyond its identity: section keys group leaves, and a leaf key may carry a display format after a colon (value:money, rate:percentage). Sections seen in production include net (value, rate, balance), supply, borrow, stake, lp, position, portfolio, media (image, animation, html), and address (backfill_percentage); the set is protocol-defined and open, so read what is present rather than assuming a fixed shape. Every yield, rate, health, and position number the product displays lives here and nowhere else: an entry with no attributes is not an entry without those numbers, it is an entry whose attributes were not requested or not indexed.", "anyOf": [ {}, {} ] }, "balance": { "type": "object", "properties": { "int": { "type": "string" }, "float": { "type": "string" }, "decimals": { "type": "number" }, "value": { "type": "string" } }, "required": [ "int" ] }, "price": {}, "relationships": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "token_id": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "standard": { "type": "string" }, "status": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "attributes": { "description": "Arbitrarily nested map holding everything indexed about this entry beyond its identity: section keys group leaves, and a leaf key may carry a display format after a colon (value:money, rate:percentage). Sections seen in production include net (value, rate, balance), supply, borrow, stake, lp, position, portfolio, media (image, animation, html), and address (backfill_percentage); the set is protocol-defined and open, so read what is present rather than assuming a fixed shape. Every yield, rate, health, and position number the product displays lives here and nowhere else: an entry with no attributes is not an entry without those numbers, it is an entry whose attributes were not requested or not indexed.", "anyOf": [ {}, {} ] }, "balance": { "type": "object", "properties": { "int": { "type": "string" }, "float": { "type": "string" }, "decimals": { "type": "number" }, "value": { "type": "string" } }, "required": [ "int" ] } }, "required": [ "token_id" ] } } }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "token_id": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "standard": { "type": "string" }, "status": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "attributes": { "description": "Arbitrarily nested map holding everything indexed about this entry beyond its identity: section keys group leaves, and a leaf key may carry a display format after a colon (value:money, rate:percentage). Sections seen in production include net (value, rate, balance), supply, borrow, stake, lp, position, portfolio, media (image, animation, html), and address (backfill_percentage); the set is protocol-defined and open, so read what is present rather than assuming a fixed shape. Every yield, rate, health, and position number the product displays lives here and nowhere else: an entry with no attributes is not an entry without those numbers, it is an entry whose attributes were not requested or not indexed.", "anyOf": [ {}, {} ] }, "balance": { "type": "object", "properties": { "int": { "type": "string" }, "float": { "type": "string" }, "decimals": { "type": "number" }, "value": { "type": "string" } }, "required": [ "int" ] } }, "required": [ "token_id" ] } }, "visibility": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "protocol": { "type": "string" }, "action": { "type": "string" }, "capability": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label", "description" ] } }, "required": [ "protocol", "action" ] } } }, "required": [ "chain_id", "address" ] } } } } } } } }, "put": { "operationId": "getPositions", "summary": "Get position(s)", "description": "Returns every position an address holds across every protocol Plug indexes: fungible balances, non-fungible holdings, and the non-tokenized positions that never show up in a wallet.\n\nA lending market deposit, an LP range, a staked balance, a vault share: most of what an address is worth has no token in the wallet to prove it. The indexer derives these positions from onchain events and keeps every number a protocol tracks about them, yields, rates, health, value, in the attributes of each entry.\n\nReach for it to render a portfolio, to find the balance a strategy is about to act on, or to answer what is this address actually holding without connecting a wallet or touching a key.", "tags": [ "Address" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "filter[chain_id]", "in": "query", "required": false, "description": "Filter results to specific chains from the listed of supported options.", "schema": { "type": "array", "items": { "type": "number" } } }, { "name": "filter[standard]", "in": "query", "required": false, "description": "Filter results to specific token standards.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "erc:20", "erc:721", "erc:1155", "erc:4626", "native", "position" ] } } }, { "name": "filter[protocol]", "in": "query", "required": false, "description": "Filter results to specific protocols from the listed of supported options.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[address]", "in": "query", "required": false, "description": "Filter results to specific contract addresses.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[token_id]", "in": "query", "required": false, "description": "Filter results to specific token ids.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "filter[verified]", "in": "query", "required": false, "description": "Filter results to verified or unverified contracts.", "schema": { "type": "boolean", "enum": [ true, false ] } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Filter results by status. Supports 'pinned' and 'hidden' as special visibility filters.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "search[all]", "in": "query", "required": false, "description": "Search by name or symbol.", "schema": { "type": "string" } }, { "name": "search[name]", "in": "query", "required": false, "description": "Search by name only.", "schema": { "type": "string" } }, { "name": "search[symbol]", "in": "query", "required": false, "description": "Search by symbol only.", "schema": { "type": "string" } }, { "name": "action[refresh]", "in": "query", "required": false, "description": "Refresh underlying metadata of returned items.", "schema": { "type": "boolean", "enum": [ true, false ] } }, { "name": "action[hide]", "in": "query", "required": false, "description": "Hide positions from the response.", "schema": { "type": "boolean", "enum": [ true, false ] } }, { "name": "action[visibility]", "in": "query", "required": false, "description": "Set visibility for matched positions. Values: 'pinned', 'hidden', or '' (clear).", "schema": { "type": "string" } }, { "name": "sort[by]", "in": "query", "required": false, "description": "Field to sort results by.", "schema": { "type": "string", "enum": [ "value", "name", "symbol" ] } }, { "name": "sort[direction]", "in": "query", "required": false, "description": "Sort direction (ascending or descending).", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit[count]", "in": "query", "required": false, "description": "Maximum number of results to return.", "schema": { "type": "number" } }, { "name": "limit[offset]", "in": "query", "required": false, "description": "Number of results to skip for pagination.", "schema": { "type": "number" } }, { "name": "limit[groups]", "in": "query", "required": false, "description": "Group results by specified fields.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Get position(s)", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": { "type": "object", "properties": { "deposit_value:money": { "description": "Total USD value deposited across all positions.", "type": "string" }, "debt_value:money": { "description": "Total USD value borrowed across all positions.", "type": "string" }, "net_worth:money": { "description": "Deposit value minus debt value in USD.", "type": "string" }, "net_carry_apy:percent": { "description": "Net carry APY across all positions as a 0..1 fraction, the unit every :percent value carries; the display layer scales ×100.", "type": "string" }, "claimable_value:money": { "description": "Total USD value of unclaimed rewards.", "type": "string" } } }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "token_id": { "type": "string" }, "standard": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "icon": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "attributes": { "description": "Arbitrarily nested map holding everything indexed about this entry beyond its identity: section keys group leaves, and a leaf key may carry a display format after a colon (value:money, rate:percentage). Sections seen in production include net (value, rate, balance), supply, borrow, stake, lp, position, portfolio, media (image, animation, html), and address (backfill_percentage); the set is protocol-defined and open, so read what is present rather than assuming a fixed shape. Every yield, rate, health, and position number the product displays lives here and nowhere else: an entry with no attributes is not an entry without those numbers, it is an entry whose attributes were not requested or not indexed.", "anyOf": [ {}, {} ] }, "balance": { "type": "object", "properties": { "int": { "type": "string" }, "float": { "type": "string" }, "decimals": { "type": "number" }, "value": { "type": "string" } }, "required": [ "int" ] }, "price": {}, "relationships": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "token_id": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "standard": { "type": "string" }, "status": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "attributes": { "description": "Arbitrarily nested map holding everything indexed about this entry beyond its identity: section keys group leaves, and a leaf key may carry a display format after a colon (value:money, rate:percentage). Sections seen in production include net (value, rate, balance), supply, borrow, stake, lp, position, portfolio, media (image, animation, html), and address (backfill_percentage); the set is protocol-defined and open, so read what is present rather than assuming a fixed shape. Every yield, rate, health, and position number the product displays lives here and nowhere else: an entry with no attributes is not an entry without those numbers, it is an entry whose attributes were not requested or not indexed.", "anyOf": [ {}, {} ] }, "balance": { "type": "object", "properties": { "int": { "type": "string" }, "float": { "type": "string" }, "decimals": { "type": "number" }, "value": { "type": "string" } }, "required": [ "int" ] } }, "required": [ "token_id" ] } } }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "token_id": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "standard": { "type": "string" }, "status": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "attributes": { "description": "Arbitrarily nested map holding everything indexed about this entry beyond its identity: section keys group leaves, and a leaf key may carry a display format after a colon (value:money, rate:percentage). Sections seen in production include net (value, rate, balance), supply, borrow, stake, lp, position, portfolio, media (image, animation, html), and address (backfill_percentage); the set is protocol-defined and open, so read what is present rather than assuming a fixed shape. Every yield, rate, health, and position number the product displays lives here and nowhere else: an entry with no attributes is not an entry without those numbers, it is an entry whose attributes were not requested or not indexed.", "anyOf": [ {}, {} ] }, "balance": { "type": "object", "properties": { "int": { "type": "string" }, "float": { "type": "string" }, "decimals": { "type": "number" }, "value": { "type": "string" } }, "required": [ "int" ] } }, "required": [ "token_id" ] } }, "visibility": { "type": "string" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "protocol": { "type": "string" }, "action": { "type": "string" }, "capability": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "value", "label", "description" ] } }, "required": [ "protocol", "action" ] } } }, "required": [ "chain_id", "address" ] } } } } } } } } }, "post": { "operationId": "getContext", "summary": "Get context", "description": "Returns the options every input of an action accepts for this address: the tokens it holds, the pools that exist, the chains it can act on, resolved against the live catalog.\n\nThis is the surface the composer runs on. Send the action sequence being drafted and the response carries a valid option set for each unfilled input, plus request-scoped context such as a swap quote or a live maximum projected over what has been filled so far. The options are already filtered to what would actually compile.\n\nReach for it while building a transaction, once per edit, so the person or agent doing the composing only ever sees choices that work.", "tags": [ "Transaction" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "filter[chain_id]", "in": "query", "required": false, "description": "Filter results to specific chains from the listed of supported options.", "schema": { "type": "number" } }, { "name": "filter[protocol]", "in": "query", "required": false, "description": "Filter results to specific protocols from the listed of supported options.", "schema": { "type": "string" } }, { "name": "filter[action]", "in": "query", "required": false, "description": "Filter results to specific actions from the listed of supported options.", "schema": { "type": "string" } }, { "name": "filter[unlisted]", "in": "query", "required": false, "description": "Include unlisted contracts in the results.", "schema": { "type": "boolean", "enum": [ true, false ] } }, { "name": "search", "in": "query", "required": false, "description": "Search within the returned options by input index of an action sentence. This is helpful when letting users refine the options shown for a specific action input such as tokens, vaults or liquidity pools.", "schema": { "type": "string" } }, { "name": "intent", "in": "query", "required": false, "description": "Whether an action's options are scoped to the caller's holdings (imperative, acting now) or the full universe of valid targets (declarative, composing a flow). Defaults to declarative.", "schema": { "type": "string", "enum": [ "imperative", "declarative" ] } }, { "name": "input", "in": "query", "required": false, "description": "The focused input index whose option list is being paginated. Paired with limit; the response windows only this input's list.", "schema": { "type": "number" } }, { "name": "selections", "in": "query", "required": false, "description": "Values already chosen for the focused input's dependency inputs, keyed by input index, so a dependent list (e.g. a market that hangs off a chosen token) windows against its parent.", "schema": { "type": "string" } }, { "name": "draft", "in": "query", "required": false, "description": "The full partial assignment, every input the user has filled so far keyed by input index, so the server can project request-scoped meta (a swap quote, a live max) over the complete in-flight request.", "schema": { "type": "string" } }, { "name": "limit[count]", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "limit[offset]", "in": "query", "required": false, "schema": { "type": "number" } } ], "responses": { "200": { "description": "Get context", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "object", "null" ], "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "symbol": { "type": "string" }, "icon": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "icon": { "type": "string" }, "external": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] } }, "block_time": { "type": "number" } }, "required": [ "chain_id", "address", "name", "symbol", "decimals", "icon", "external", "block_time" ] } }, "links": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "url": { "type": "string" } }, "required": [ "kind", "url" ] } }, "actions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "type": { "type": "string" }, "sentence": { "type": "object", "properties": { "raw": { "type": "string" }, "template": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "anyOf": [ {}, {} ] }, "defaultValue": { "type": "string" }, "requires": { "type": "array", "items": { "type": "number" } }, "delimiter": { "type": "string" }, "hidden": { "type": "boolean" }, "coil": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "qualifiers": { "type": "array", "items": { "description": "Recursive structure" } }, "dynamic": { "type": "boolean" }, "reference": { "type": "number" } }, "required": [ "kind" ] } }, "selectorTags": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "kind": { "description": "Recursive structure" }, "value": { "description": "Recursive structure" }, "qualifiers": { "description": "Recursive structure" }, "dynamic": { "description": "Recursive structure" }, "reference": { "description": "Recursive structure" } } } } } } } }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "anyOf": [ { "type": "string" }, {} ] }, "offset": { "type": "number" }, "dynamic": { "type": "boolean" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "qualifiers": { "type": "array", "items": { "description": "Recursive structure" } }, "dynamic": { "type": "boolean" }, "reference": { "type": "number" } }, "required": [ "kind" ] } }, "selectorTags": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "kind": { "description": "Recursive structure" }, "value": { "description": "Recursive structure" }, "qualifiers": { "description": "Recursive structure" }, "dynamic": { "description": "Recursive structure" }, "reference": { "description": "Recursive structure" } } } } }, "selectorInput": { "type": "number" } }, "required": [ "name", "type", "offset" ] } } }, "required": [ "raw", "template", "inputs" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "icon": { "type": "string" }, "attributes": { "type": "object", "properties": { "is:user_specific": { "type": "boolean" }, "is:unlisted": { "type": "boolean" } } }, "feeds": { "type": "array", "items": { "type": "string" } }, "options": { "anyOf": [ {}, {}, {} ] }, "meta": { "type": "object", "properties": { "action": { "type": "object", "additionalProperties": {} }, "inputs": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } } } } }, "required": [ "type", "sentence", "name", "description", "icon" ] } } }, "required": [ "name", "symbol", "icon", "tags", "chains" ] } } } } } } } } } }, "/address/{address}/activity": { "get": { "operationId": "getActivity", "summary": "Get activity", "description": "Returns the onchain transaction history of an address, paginated and sorted by block number descending.\n\nEach entry is a settled transaction with what it moved: the flows, approvals, and counterparties involved, normalized across every chain Plug indexes rather than raw logs left for the caller to decode.\n\nReach for it to render an activity feed, to reconcile what a strategy actually did against what it was meant to do, or to walk an address's history without running an archive node.", "tags": [ "Address" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "filter[chain_id]", "in": "query", "required": false, "description": "Filter results to a specific chain from the listed of supported options.", "schema": { "type": "number" } }, { "name": "limit[count]", "in": "query", "required": false, "description": "Maximum number of results to return (1-200, default 50).", "schema": { "type": "number" } }, { "name": "limit[offset]", "in": "query", "required": false, "description": "Number of results to skip for pagination.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Get activity", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "array", "null" ], "items": {} } } } } } } } } }, "/address/{address}/transaction/": { "get": { "operationId": "getTransactions", "summary": "Get transaction(s)", "description": "Returns the transactions Plug has saved for an address: every intent created through the platform, with its status, schedule, and execution record, narrowed by whatever filters are applied.\n\nThese are Plug's own records, not chain history. A row exists from the moment a transaction is created, tracks its life through scheduling, simulation, submission, and settlement, and keeps the verdict when something fails. Listing is all this surface does.\n\nReach for it to show a user their pending and past transactions or to poll the state of an intent that was submitted earlier. Compiling new calldata belongs to the create step, not here.", "tags": [ "Transaction" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "filter[id]", "in": "query", "required": false, "description": "Filter results to a specific transaction id.", "schema": { "type": "string" } }, { "name": "filter[chain_id]", "in": "query", "required": false, "description": "Filter results to specific chains from the listed of supported options.", "schema": { "type": "number" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Filter results to specific transaction statuses.", "schema": { "type": "string", "enum": [ "pending", "confirmed", "failed" ] } } ], "responses": { "200": { "description": "Get transaction(s)", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "chain_id": { "type": "number" }, "address": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "gas_limit": { "type": [ "number", "null" ] }, "inputs": { "type": [ "array", "null" ], "items": {} }, "steps": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] }, "execution_mode": { "type": "string" }, "owner_address": { "type": "string" }, "plugs_hash": { "type": "string" }, "scheduler_status": { "type": "string" }, "last_error": { "type": "string" }, "verdict": { "type": "string" }, "failing_condition": { "type": "number" }, "last_simmed_block": { "type": "number" } }, "required": [ "id", "status", "chain_id", "address", "created_at", "updated_at" ] } } } } } } } } }, "post": { "operationId": "createTransaction", "summary": "Create transaction", "description": "Constructs and compiles transaction calldata from structured inputs, returning a record ready for signing and submission.\n\nHand it the steps of the transaction as action references with filled inputs and it resolves them through the catalog, compiles the calldata, and persists a transaction row that tracks the intent from here to settlement. The response carries everything a wallet needs to sign.\n\nThis is the build step. Listing existing records is the GET on the same path, and the pure preview that persists nothing is the compile surface.", "tags": [ "Transaction" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "input[chain_id]", "in": "query", "required": true, "description": "The chain to create the transaction for.", "schema": { "type": "number" } }, { "name": "input[deadline]", "in": "query", "required": false, "description": "A unix timestamp after which the transaction is no longer valid.", "schema": { "type": "number" } }, { "name": "input[owner]", "in": "query", "required": false, "description": "The account the draft executes for: a standard:wallet slot filled with \"yourself\" resolves to this address. Absent, the authenticated session's address; absent both, wallet-self slots stay on the executing account.", "schema": { "type": "string" } }, { "name": "input[gas_limit]", "in": "query", "required": false, "description": "Gas limit recorded on the created transaction.", "schema": { "type": "number" } }, { "name": "input[steps]", "in": "query", "required": true, "description": "The steps/actions to include in the transaction.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Create transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "chain_id": { "type": "number" }, "address": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "gas_limit": { "type": [ "number", "null" ] }, "inputs": { "type": [ "array", "null" ], "items": {} }, "steps": {}, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] }, "execution_mode": { "type": "string" }, "owner_address": { "type": "string" }, "plugs_hash": { "type": "string" }, "scheduler_status": { "type": "string" }, "last_error": { "type": "string" }, "verdict": { "type": "string" }, "failing_condition": { "type": "number" }, "last_simmed_block": { "type": "number" }, "outputs": { "type": [ "array", "null" ], "items": {} }, "relay": { "type": [ "object", "null" ], "properties": { "typed_data": { "type": "object", "properties": { "types": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } } }, "primaryType": { "type": "string" }, "domain": { "type": "object", "additionalProperties": {} }, "message": { "type": "object", "additionalProperties": {} } }, "required": [ "types", "primaryType", "domain", "message" ] }, "plugs": { "type": "array", "items": { "type": "string" } }, "state": { "type": "array", "items": { "type": "string" } }, "manifest": { "type": "array", "items": { "type": "object", "properties": { "token_in": { "type": "string" }, "token_out": { "type": "string" }, "amount_in": { "type": "number" }, "executor_slot": { "type": "number" }, "route_slot": { "type": "number" } }, "required": [ "token_in", "token_out", "amount_in", "executor_slot", "route_slot" ] } } }, "required": [ "typed_data", "plugs", "state", "manifest" ] } }, "required": [ "id", "status", "chain_id", "address", "created_at", "updated_at" ] } } } } } } } }, "put": { "operationId": "submitTransaction", "summary": "Submit transaction", "description": "Broadcasts a signed intent bundle.\n\nThe signature must come from the owning wallet, which makes this the one surface in the API that cannot act on an arbitrary address. Everything before it, reading, composing, compiling, is open; the moment value can move, the wallet is the gate. The submitted program carries its own conditions, so execution happens when they are met, not necessarily when this call returns.\n\nReach for it as the final step of the flow the create and compile surfaces set up: sign what they produced, hand it over, and track the record through the transactions list.", "tags": [ "Transaction" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chain_id": { "type": "number" }, "owner": { "type": "string" }, "salt": { "type": "string" }, "plugs": { "type": "array", "items": { "type": "string" } }, "state": { "type": "array", "items": { "type": "string" } }, "signature": { "type": "string" }, "manifest": { "type": "array", "items": { "type": "object", "properties": { "token_in": { "type": "string" }, "token_out": { "type": "string" }, "amount_in": { "type": "number" }, "executor_slot": { "type": "number" }, "route_slot": { "type": "number" } }, "required": [ "token_in", "token_out", "amount_in", "executor_slot", "route_slot" ] } } }, "required": [ "chain_id", "owner", "plugs", "state", "signature", "manifest" ] } } } }, "responses": { "200": { "description": "Submit transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_hash": { "type": "string" } }, "required": [ "transaction_hash" ] } } } } } }, "delete": { "operationId": "cancelTransaction", "summary": "Cancel transaction", "description": "Cancels a scheduled or pending intent owned by the address.\n\nAn armed intent is a standing order: it will fire whenever its conditions are met, whether or not anyone is watching. Cancelation is how a standing order dies before it fires. Rows that have already settled are history and stay untouched.\n\nReach for it when a strategy is retired, a schedule is no longer wanted, or a pending transaction was a mistake, and confirm the row's status through the transactions list afterward.", "tags": [ "Transaction" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "id", "in": "query", "required": true, "description": "The intent row id to cancel.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancel transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "scheduler_status": { "type": "string" }, "execution_mode": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] } }, "required": [ "id", "status" ] } } } } } } }, "/address/{address}/history": { "get": { "operationId": "getSeries", "summary": "Get series", "description": "Returns time series for an address: price candles, balance history, and portfolio value over time, bucketed for charting.\n\nWhich groups a bucket carries follows what was asked for, so the same surface serves a price chart, a balance sparkline, or a full portfolio curve. Values arrive in the units the display layer expects, with the bucketing already done server side.\n\nReach for it any time a number needs to become a line: charting a holding, showing portfolio drift, or feeding a strategy the recent history of what it manages.", "tags": [ "Address" ], "parameters": [ { "name": "address", "in": "path", "required": true, "description": "The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.", "schema": { "type": "string" }, "example": "0x62180042606624f02d8a130da8a3171e9b33894d" }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "filter[address]", "in": "query", "required": false, "description": "Token or contract address for token/collectible history.", "schema": { "type": "string" } }, { "name": "filter[token_id]", "in": "query", "required": false, "description": "Token ID for collectible history.", "schema": { "type": "string" } }, { "name": "filter[chain_id]", "in": "query", "required": false, "description": "Chain ID to query. Defaults to mainnet.", "schema": { "type": "number" } }, { "name": "time[before]", "in": "query", "required": false, "description": "Upper bound unix timestamp for the time window.", "schema": { "type": "number" } }, { "name": "time[from]", "in": "query", "required": false, "description": "Start unix timestamp. Defaults to 24h before to.", "schema": { "type": "number" } }, { "name": "time[to]", "in": "query", "required": false, "description": "End unix timestamp. Defaults to now.", "schema": { "type": "number" } }, { "name": "time[resolution]", "in": "query", "required": false, "description": "Time bucket resolution (e.g., 1h, 1d, all). Auto-selected if omitted.", "schema": { "type": "string" } }, { "name": "sort[direction]", "in": "query", "required": false, "description": "Sort direction for results.", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "limit[count]", "in": "query", "required": false, "description": "Maximum number of results to return (max 500).", "schema": { "type": "number" } }, { "name": "limit[offset]", "in": "query", "required": false, "description": "Number of results to skip for pagination.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Get series", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestamp": { "type": "number" }, "balance": { "type": "object", "properties": { "int": { "description": "Raw balance in base units.", "type": "string" }, "float": { "description": "Balance scaled by the token's decimals.", "type": "string" }, "value": { "description": "Balance valued in USD.", "type": "string" } } }, "price": { "type": "object", "properties": { "open": { "type": "string" }, "high": { "type": "string" }, "low": { "type": "string" }, "close": { "type": "string" }, "change": { "type": "string" } } }, "position": { "type": "object", "properties": { "deposit_value": { "description": "USD value supplied to the position.", "type": "string" }, "debt_value": { "description": "USD value borrowed against it.", "type": "string" }, "assets": { "description": "Per-asset attributes keyed by asset address.", "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "portfolio": { "type": "object", "properties": { "value": { "description": "Total portfolio value in USD.", "type": "string" } } } }, "required": [ "timestamp" ] } } } } } } } } } }, "/transaction/": { "put": { "operationId": "compileTransaction", "summary": "Compile transaction", "description": "Compiles a draft action sequence into coil options, output manifests, and simulated slot values without persisting anything.\n\nThis is the preview step the composer runs on every edit. It is not bound to a wallet, it never submits, and nothing it computes outlives the response: it exists so a draft can be checked against the compiler that will eventually execute it, every keystroke, for free.\n\nReach for it to validate a sequence as it is being written, to learn what each step will output before anything is signed, or to build composer-grade tooling of your own on the same contract the app uses.", "tags": [ "Transaction" ], "parameters": [ { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "input[chain_id]", "in": "query", "required": true, "description": "The chain to compile the transaction for.", "schema": { "type": "number" } }, { "name": "input[owner]", "in": "query", "required": false, "description": "The simulation subject: drafts compile and simulate at this address's counterfactual socket, so user-specific reads observe its real chain state. Absent, drafts simulate on the synthetic account.", "schema": { "type": "string" } }, { "name": "input[steps]", "in": "query", "required": true, "description": "The steps/actions to compile.", "schema": { "type": "string" } }, { "name": "input[overrides]", "in": "query", "required": false, "description": "Debugger hypotheses: step.path keys naming read outputs, 0x-hex raw slot values. The program re-executes with each read pinned to its stated value; a draft carrying overrides projects fully and is never signable.", "schema": { "type": "string" } }, { "name": "input[signature]", "in": "query", "required": false, "description": "The owner's EIP-712 signature over the lowered program. Present on the second lowering pass: with it the response carries the complete wallet_sendCalls batch including the factory createAndExecute call, simulated as the exact batch that will execute. Without it the response carries the typed data to sign.", "schema": { "type": "string" } }, { "name": "input[deadline]", "in": "query", "required": false, "description": "Unix seconds for the program deadline. The deadline is part of the signed typed data, so a signed re-simulation must echo the value that was signed; a different deadline is a different program. Absent or zero, the server stamps its default TTL.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Compile transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "object", "null" ], "properties": { "options": { "type": [ "array", "null" ], "items": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "ref": { "type": "string" } }, "required": [ "name", "type", "ref" ] } } } }, "outputs": { "type": [ "array", "null" ], "items": {} }, "parameters": { "description": "Inputs the draft leaves unbound for execution time.", "type": [ "array", "null" ], "items": { "type": "object", "properties": { "step": { "type": "number" }, "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "step", "name", "type" ] } }, "graph": { "type": [ "object", "null" ], "properties": { "nodes": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "number" }, "protocol": { "type": "string" }, "action": { "type": "string" }, "outputs": { "type": [ "array", "null" ], "items": {} }, "ir": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "index": { "type": "number" }, "kind": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "dead": { "type": [ "boolean", "null" ] }, "reads": { "type": [ "array", "null" ], "items": { "type": "number" } }, "writes": { "type": [ "array", "null" ], "items": { "type": "number" } } }, "required": [ "index", "kind" ] } } }, "required": [ "step", "protocol", "action" ] } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "kind": { "enum": [ "output", "input", "state" ], "type": "string" }, "source": { "type": "number" }, "source_slot": { "type": "number" }, "source_name": { "type": [ "string", "null" ] }, "source_tags": {}, "fields": { "type": [ "array", "null" ], "items": { "type": "number" } }, "target": { "type": "number" }, "target_input": { "type": "string" }, "ref": { "type": "string" } }, "required": [ "kind", "source", "source_slot", "target", "target_input", "ref" ] } } }, "required": [ "nodes", "edges" ] }, "simulation": { "type": [ "object", "null" ], "properties": { "verdict": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "failing_step": { "type": [ "number", "null" ] }, "gas_used": { "type": [ "number", "null" ] }, "block_number": { "type": [ "number", "null" ] }, "outputs": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "action_index": { "type": "number" }, "action": { "type": "string" }, "assumed": { "type": [ "boolean", "null" ] }, "slots": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": {}, "slot": { "type": "number" }, "path": { "type": "string" }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "qualifiers": { "type": "array", "items": { "type": "string" } }, "dynamic": { "type": "boolean" }, "reference": { "type": "number" } }, "required": [ "kind" ] } }, "value": { "type": [ "string", "null" ] } }, "required": [ "name", "type", "slot", "path" ] } } }, "required": [ "action_index", "action", "slots" ] } }, "exclusions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "step": { "type": "number" }, "cause": { "type": "string" } }, "required": [ "step", "cause" ] } } } }, "calls": { "description": "The executable wallet_sendCalls batch. Present only when the request carried the owner's signature and the simulation verdict is executable.", "type": [ "array", "null" ], "items": { "type": "object", "properties": { "to": { "type": "string" }, "value": { "type": "string" }, "data": { "type": "string" } }, "required": [ "to", "value", "data" ] } }, "program": { "description": "The typed data to sign and the account it executes on. Present when the draft is complete and an owner was given; absent once a signature is supplied.", "type": [ "object", "null" ], "properties": { "socket": { "type": "string" }, "salt": { "type": "string" }, "deadline": { "type": "number" }, "typed_data": { "type": "object", "properties": { "types": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } } }, "primaryType": { "type": "string" }, "domain": { "type": "object", "additionalProperties": {} }, "message": { "type": "object", "additionalProperties": {} } }, "required": [ "types", "primaryType", "domain", "message" ] } }, "required": [ "socket", "salt", "deadline", "typed_data" ] } } } } } } } } } } }, "/chain": { "get": { "operationId": "getChains", "summary": "Get chain(s)", "description": "Returns the configuration and metadata of every blockchain network Plug indexes and executes on.\n\nEach entry carries what a caller needs to speak to a chain through Plug: its id, its identity, and the platform-level configuration that decides how it is indexed and executed against. The list is the authority on where Plug operates; anything not in it is not supported yet.\n\nReach for it to populate a chain picker, to validate a chain id before composing against it, or to discover what is supported without hardcoding a list that will rot.", "tags": [ "Chain" ], "parameters": [ { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } }, { "name": "filter[chain_id]", "in": "query", "required": false, "description": "Filter results to specific chains from the listed of supported options.", "schema": { "type": "array", "items": { "type": "number" } } } ], "responses": { "200": { "description": "Get chain(s)", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "object", "null" ], "properties": { "chain_id": { "type": "number" }, "address": { "type": "string" }, "name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" }, "icon": { "type": "string" }, "external": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] } }, "block_time": { "type": "number" } }, "required": [ "chain_id", "address", "name", "symbol", "decimals", "icon", "external", "block_time" ] } } } } } } } } }, "/cdn/{encoded_url}/color": { "get": { "operationId": "getColor", "summary": "Get color", "description": "Returns the dominant color of a hosted image along with a text color that stays readable on top of it.\n\nThe pair is computed once and served from the CDN, so surfaces themed around remote assets, token icons, protocol logos, NFT media, get their palette in one cheap call instead of shipping color extraction to the client.\n\nReach for it whenever UI wraps an image it has never seen: card backgrounds, hover washes, any place the design should take its color from the asset instead of a default.", "tags": [ "CDN" ], "parameters": [ { "name": "encoded_url", "in": "path", "required": true, "description": "Base64url encoding of the absolute asset URL, the same segment the /cdn proxy serves the image from.", "schema": { "type": "string" } }, { "name": "Accept", "in": "header", "required": true, "description": "For a typical single-time JSON response, set this to application/json. To receive realtime updates through a stream, set this to text/event-stream.", "schema": { "type": "string", "enum": [ "application/json", "text/event-stream" ], "default": "application/json" } } ], "responses": { "200": { "description": "Get color", "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "self": { "type": "string" }, "prev": { "type": "string" }, "next": { "type": "string" } }, "required": [ "self" ] }, "headers": {}, "data": { "type": [ "object", "null" ], "properties": { "color": { "type": "string" }, "textColor": { "type": "string" } }, "required": [ "color", "textColor" ] } } } } } } } } }, "/auth/nonce": { "get": { "operationId": "getNonce", "summary": "Get nonce", "description": "Issues a one-time nonce to embed in a Sign-In with Ethereum message.\n\nThe nonce binds the message the wallet is about to sign to this single authentication attempt, which is what makes a replayed signature worthless. It is step one of three: nonce, verify, refresh.\n\nReach for it at the start of wallet authentication, put the value in the SIWE message, and send the signed result to the verify surface.", "tags": [ "Authentication" ], "responses": { "200": { "description": "Get nonce", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "nonce": { "description": "One-time value to embed in the SIWE message before signing.", "type": "string" }, "expires_at": { "description": "RFC 3339 timestamp after which the nonce is rejected.", "type": "string" } }, "required": [ "nonce", "expires_at" ] } }, "required": [ "data" ] } } } } } } }, "/auth/verify": { "post": { "operationId": "verifySignature", "summary": "Verify signature", "description": "Exchanges a signed Sign-In with Ethereum message for an access and refresh token pair.\n\nThe server checks the signature against the message, confirms the nonce is the one it issued, and mints the pair: a short-lived access token that authenticates requests and a refresh token that rotates it. Step two of three in wallet authentication.\n\nReach for it with the output of the wallet's signing prompt, then hold both tokens; the session lives exactly as long as the refresh rotation continues.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "description": "The exact SIWE message that was signed, verbatim.", "type": "string" }, "signature": { "description": "Hex signature of the SIWE message produced by the wallet.", "type": "string" } }, "required": [ "message", "signature" ] } } } }, "responses": { "200": { "description": "Verify signature", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "access_token": { "description": "Bearer token for the Authorization header.", "type": "string" }, "refresh_token": { "description": "Token used to rotate the pair once the access token expires.", "type": "string" }, "expires_in": { "description": "Access token lifetime in seconds from issuance.", "type": "number" } }, "required": [ "access_token", "refresh_token", "expires_in" ] } }, "required": [ "data" ] } } } } } } }, "/auth/refresh": { "post": { "operationId": "refreshToken", "summary": "Refresh token", "description": "Rotates an expiring access token using its refresh token.\n\nAccess tokens are deliberately short-lived; the refresh token is what turns a signature made once into a session that lasts. Each rotation returns a fresh pair, so the caller always holds current credentials without asking the wallet to sign again. Step three of three in wallet authentication.\n\nReach for it just before the access token expires, or on the first rejected request, and replace both stored tokens with what comes back.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "description": "The refresh token issued by /auth/verify or a prior refresh.", "type": "string" } }, "required": [ "refresh_token" ] } } } }, "responses": { "200": { "description": "Refresh token", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "access_token": { "description": "Bearer token for the Authorization header.", "type": "string" }, "refresh_token": { "description": "Token used to rotate the pair once the access token expires.", "type": "string" }, "expires_in": { "description": "Access token lifetime in seconds from issuance.", "type": "number" } }, "required": [ "access_token", "refresh_token", "expires_in" ] } }, "required": [ "data" ] } } } } } } }, "/auth/session": { "get": { "operationId": "getSession", "summary": "Get session", "description": "Resolves the address that the presented access token authenticates.\n\nIt is the whoami of the API: given nothing but the bearer token, it answers which wallet this session belongs to, which is exactly what a server-side consumer needs to trust a request without re-verifying a signature.\n\nReach for it to restore a session on load, to guard a route, or to confirm a token still lives before doing something that needs it.", "tags": [ "Authentication" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Get session", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "address": { "description": "The EVM address the presented access token authenticates.", "type": "string" } }, "required": [ "address" ] } }, "required": [ "data" ] } } } } } } } } }