# Plug API

Programmable Ethereum transactions without smart contracts. Read any EVM address, resolve what an action needs, compile the calldata, and submit it.

Base URL: https://api.plug.to

Authentication: none for reads. Submitting a signed intent bundle is the only surface bound to a wallet.

Streaming: send `Accept: text/event-stream` for realtime updates instead of a single JSON response.

OpenAPI: https://plug.to/docs/openapi.json

The public system is in alpha and not yet recommended for production use. Changes are frequent.

## Address

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.

### Get address

`GET https://api.plug.to/address/{address}/`

Returns everything Plug knows about an address at the identity level: its metadata and the signal flags the indexing graph has raised on it.

The 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.

Reach 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.

Reference: https://plug.to/docs/get-address/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object, optional, nullable)
  - chain_id (integer, required)
  - address (string, required)
  - token_id (string, optional)
  - standard (string, optional)
  - name (string, optional)
  - symbol (string, optional)
  - decimals (integer, optional)
  - icon (string, optional)
  - description (string, optional)
  - status (string, optional)
  - attributes (Record<string, string | self>, optional) — 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.
    - value (string | self, required)
  - balance (object, optional)
    - int (string, required)
    - float (string, optional)
    - decimals (integer, optional)
    - value (string, optional)
  - price (effects, optional)
  - relationships (Record<string, array>, optional)
    - value (object[], required)
      - chain_id (integer, optional)
      - address (string, optional)
      - token_id (string, required)
      - name (string, optional)
      - symbol (string, optional)
      - decimals (integer, optional)
      - standard (string, optional)
      - status (string, optional)
      - icon (string, optional)
      - description (string, optional)
      - attributes (Record<string, string | self>, optional) — 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.
        - value (string | self, required)
      - balance (object, optional)
        - int (string, required)
        - float (string, optional)
        - decimals (integer, optional)
        - value (string, optional)
  - tokens (object[], optional)
    - chain_id (integer, optional)
    - address (string, optional)
    - token_id (string, required)
    - name (string, optional)
    - symbol (string, optional)
    - decimals (integer, optional)
    - standard (string, optional)
    - status (string, optional)
    - icon (string, optional)
    - description (string, optional)
    - attributes (Record<string, string | self>, optional) — 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.
      - value (string | self, required)
    - balance (object, optional)
      - int (string, required)
      - float (string, optional)
      - decimals (integer, optional)
      - value (string, optional)
  - visibility (string, optional)
  - actions (object[], optional)
    - protocol (string, required)
    - action (string, required)
    - capability (object, optional)
      - value (string, required)
      - label (string, required)
      - description (string, required)

Example:

```
GET https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/
```

### Get position(s)

`PUT https://api.plug.to/address/{address}/`

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.

A 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.

Reach 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.

Reference: https://plug.to/docs/get-positions/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- filter[chain_id] (integer[], optional) — Filter results to specific chains from the listed of supported options.
- filter[standard] (string[], optional, one of erc:20, erc:721, erc:1155, erc:4626, native, position) — Filter results to specific token standards.
- filter[protocol] (string[], optional) — Filter results to specific protocols from the listed of supported options.
- filter[address] (string[], optional) — Filter results to specific contract addresses.
- filter[token_id] (string[], optional) — Filter results to specific token ids.
- filter[verified] (boolean, optional, one of true, false) — Filter results to verified or unverified contracts.
- filter[status] (string[], optional) — Filter results by status. Supports 'pinned' and 'hidden' as special visibility filters.
- search[all] (string, optional) — Search by name or symbol.
- search[name] (string, optional) — Search by name only.
- search[symbol] (string, optional) — Search by symbol only.
- action[refresh] (boolean, optional, one of true, false) — Refresh underlying metadata of returned items.
- action[hide] (boolean, optional, one of true, false) — Hide positions from the response.
- action[visibility] (string, optional) — Set visibility for matched positions. Values: 'pinned', 'hidden', or '' (clear).
- sort[by] (string, optional, one of value, name, symbol) — Field to sort results by.
- sort[direction] (string, optional, one of asc, desc) — Sort direction (ascending or descending).
- limit[count] (integer, optional) — Maximum number of results to return.
- limit[offset] (integer, optional) — Number of results to skip for pagination.
- limit[groups] (string[], optional) — Group results by specified fields.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (object, optional)
  - deposit_value:money (string, optional) — Total USD value deposited across all positions.
  - debt_value:money (string, optional) — Total USD value borrowed across all positions.
  - net_worth:money (string, optional) — Deposit value minus debt value in USD.
  - net_carry_apy:percent (string, optional) — Net carry APY across all positions as a 0..1 fraction, the unit every :percent value carries; the display layer scales ×100.
  - claimable_value:money (string, optional) — Total USD value of unclaimed rewards.
- data (object[], optional, nullable)
  - chain_id (integer, required)
  - address (string, required)
  - token_id (string, optional)
  - standard (string, optional)
  - name (string, optional)
  - symbol (string, optional)
  - decimals (integer, optional)
  - icon (string, optional)
  - description (string, optional)
  - status (string, optional)
  - attributes (Record<string, string | self>, optional) — 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.
    - value (string | self, required)
  - balance (object, optional)
    - int (string, required)
    - float (string, optional)
    - decimals (integer, optional)
    - value (string, optional)
  - price (effects, optional)
  - relationships (Record<string, array>, optional)
    - value (object[], required)
      - chain_id (integer, optional)
      - address (string, optional)
      - token_id (string, required)
      - name (string, optional)
      - symbol (string, optional)
      - decimals (integer, optional)
      - standard (string, optional)
      - status (string, optional)
      - icon (string, optional)
      - description (string, optional)
      - attributes (Record<string, string | self>, optional) — 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.
        - value (string | self, required)
      - balance (object, optional)
        - int (string, required)
        - float (string, optional)
        - decimals (integer, optional)
        - value (string, optional)
  - tokens (object[], optional)
    - chain_id (integer, optional)
    - address (string, optional)
    - token_id (string, required)
    - name (string, optional)
    - symbol (string, optional)
    - decimals (integer, optional)
    - standard (string, optional)
    - status (string, optional)
    - icon (string, optional)
    - description (string, optional)
    - attributes (Record<string, string | self>, optional) — 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.
      - value (string | self, required)
    - balance (object, optional)
      - int (string, required)
      - float (string, optional)
      - decimals (integer, optional)
      - value (string, optional)
  - visibility (string, optional)
  - actions (object[], optional)
    - protocol (string, required)
    - action (string, required)
    - capability (object, optional)
      - value (string, required)
      - label (string, required)
      - description (string, required)

Example:

```
PUT https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/
```

### Get activity

`GET https://api.plug.to/address/{address}/activity`

Returns the onchain transaction history of an address, paginated and sorted by block number descending.

Each 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.

Reach 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.

Reference: https://plug.to/docs/get-activity/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- filter[chain_id] (integer, optional) — Filter results to a specific chain from the listed of supported options.
- limit[count] (integer, optional) — Maximum number of results to return (1-200, default 50).
- limit[offset] (integer, optional) — Number of results to skip for pagination.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (discriminatedunion[], optional, nullable)

Example:

```
GET https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/activity
```

### Get series

`GET https://api.plug.to/address/{address}/history`

Returns time series for an address: price candles, balance history, and portfolio value over time, bucketed for charting.

Which 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.

Reach 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.

Reference: https://plug.to/docs/get-series/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- filter[address] (string, optional) — Token or contract address for token/collectible history.
- filter[token_id] (string, optional) — Token ID for collectible history.
- filter[chain_id] (integer, optional) — Chain ID to query. Defaults to mainnet.
- time[before] (integer, optional) — Upper bound unix timestamp for the time window.
- time[from] (integer, optional) — Start unix timestamp. Defaults to 24h before to.
- time[to] (integer, optional) — End unix timestamp. Defaults to now.
- time[resolution] (string, optional) — Time bucket resolution (e.g., 1h, 1d, all). Auto-selected if omitted.
- sort[direction] (string, optional, one of asc, desc) — Sort direction for results.
- limit[count] (integer, optional) — Maximum number of results to return (max 500).
- limit[offset] (integer, optional) — Number of results to skip for pagination.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object[], optional, nullable)
  - timestamp (integer, required)
  - balance (object, optional)
    - int (string, optional) — Raw balance in base units.
    - float (string, optional) — Balance scaled by the token's decimals.
    - value (string, optional) — Balance valued in USD.
  - price (object, optional)
    - open (string, optional)
    - high (string, optional)
    - low (string, optional)
    - close (string, optional)
    - change (string, optional)
  - position (object, optional)
    - deposit_value (string, optional) — USD value supplied to the position.
    - debt_value (string, optional) — USD value borrowed against it.
    - assets (Record<string, Record<string, string>>, optional) — Per-asset attributes keyed by asset address.
      - value (Record<string, string>, required)
        - value (string, required)
  - portfolio (object, optional)
    - value (string, optional) — Total portfolio value in USD.

Example:

```
GET https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/history
```

## Transaction

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.

### Get context

`POST https://api.plug.to/address/{address}/`

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.

This 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.

Reach for it while building a transaction, once per edit, so the person or agent doing the composing only ever sees choices that work.

Reference: https://plug.to/docs/get-context/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- filter[chain_id] (integer, optional) — Filter results to specific chains from the listed of supported options.
- filter[protocol] (string, optional) — Filter results to specific protocols from the listed of supported options.
- filter[action] (string, optional) — Filter results to specific actions from the listed of supported options.
- filter[unlisted] (boolean, optional, one of true, false) — Include unlisted contracts in the results.
- search (string, optional) — 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.
- intent (string, optional, one of imperative, declarative) — 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.
- input (integer, optional) — The focused input index whose option list is being paginated. Paired with limit; the response windows only this input's list.
- selections (string, optional) — 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.
- draft (string, optional) — 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.
- limit[count] (integer, required)
- limit[offset] (integer, optional)

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (Record<string, object>, optional, nullable)
  - value (object, required)
    - name (string, required)
    - symbol (string, required)
    - icon (string, required)
    - description (string, optional)
    - tags (string[], required)
    - chains (object[], required)
      - chain_id (integer, required)
      - address (string, required)
      - name (string, required)
      - symbol (string, required)
      - decimals (integer, required)
      - icon (string, required)
      - external (Record<string, object>, required)
        - value (object, required)
          - name (string, required)
          - url (string, required)
      - block_time (integer, required)
    - links (object[], optional)
      - kind (string, required)
      - url (string, required)
    - actions (Record<string, object>, optional)
      - value (object, required)
        - type (string, required)
        - sentence (object, required)
          - raw (string, required)
          - template (string, required)
          - inputs (object[], required)
            - name (string, optional)
            - type (literal | object, optional)
            - defaultValue (string, optional)
            - requires (integer[], optional)
            - delimiter (string, optional)
            - hidden (boolean, optional)
            - coil (boolean, optional)
            - tags (object[], optional)
              - kind (string, required)
              - value (string, optional)
              - qualifiers (self[], optional)
              - dynamic (boolean, optional)
              - reference (integer, optional)
            - selectorTags (Record<string, array>, optional)
              - value (object[], required)
                - kind (self, optional) — Recursive structure
                - value (self, optional) — Recursive structure
                - qualifiers (self, optional) — Recursive structure
                - dynamic (self, optional) — Recursive structure
                - reference (self, optional) — Recursive structure
          - outputs (object[], optional)
            - name (string, required)
            - type (string | array, required)
            - offset (integer, required)
            - dynamic (boolean, optional)
            - tags (object[], optional)
              - kind (string, required)
              - value (string, optional)
              - qualifiers (self[], optional)
              - dynamic (boolean, optional)
              - reference (integer, optional)
            - selectorTags (Record<string, array>, optional)
              - value (object[], required)
                - kind (self, optional) — Recursive structure
                - value (self, optional) — Recursive structure
                - qualifiers (self, optional) — Recursive structure
                - dynamic (self, optional) — Recursive structure
                - reference (self, optional) — Recursive structure
            - selectorInput (integer, optional)
        - name (string, required)
        - description (string, required)
        - icon (string, required)
        - attributes (object, optional)
          - is:user_specific (boolean, optional)
          - is:unlisted (boolean, optional)
        - feeds (string[], optional)
        - options (Record<string, array | Record<string, array | self>>, optional)
          - value (array | Record<string, array | self>, required)
        - meta (object, optional)
          - action (Record<string, unknown>, optional)
            - value (unknown, required)
          - inputs (Record<string, Record<string, unknown>>, optional)
            - value (Record<string, unknown>, required)
              - value (unknown, required)

Example:

```
POST https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/
```

### Get transaction(s)

`GET https://api.plug.to/address/{address}/transaction/`

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.

These 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.

Reach 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.

Reference: https://plug.to/docs/get-transactions/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- filter[id] (string, optional) — Filter results to a specific transaction id.
- filter[chain_id] (integer, optional) — Filter results to specific chains from the listed of supported options.
- filter[status] (string, optional, one of pending, confirmed, failed) — Filter results to specific transaction statuses.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object[], optional, nullable)
  - id (string, required)
  - status (string, required)
  - chain_id (integer, required)
  - address (string, required)
  - value (string | integer, optional)
  - gas_limit (integer, optional, nullable)
  - inputs (any[], optional, nullable)
  - steps (any, optional, nullable)
  - created_at (string, required)
  - updated_at (string, required)
  - tx_hash (string, optional, nullable)
  - execution_mode (string, optional)
  - owner_address (string, optional)
  - plugs_hash (string, optional)
  - scheduler_status (string, optional)
  - last_error (string, optional)
  - verdict (string, optional)
  - failing_condition (integer, optional)
  - last_simmed_block (integer, optional)

Example:

```
GET https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/transaction/
```

### Create transaction

`POST https://api.plug.to/address/{address}/transaction/`

Constructs and compiles transaction calldata from structured inputs, returning a record ready for signing and submission.

Hand 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.

This 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.

Reference: https://plug.to/docs/create-transaction/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- input[chain_id] (integer, required) — The chain to create the transaction for.
- input[deadline] (integer, optional) — A unix timestamp after which the transaction is no longer valid.
- input[owner] (string, optional) — 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.
- input[gas_limit] (integer, optional) — Gas limit recorded on the created transaction.
- input[steps] (string, required) — The steps/actions to include in the transaction.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object, optional, nullable)
  - id (string, required)
  - status (string, required)
  - chain_id (integer, required)
  - address (string, required)
  - value (string | integer, optional)
  - gas_limit (integer, optional, nullable)
  - inputs (any[], optional, nullable)
  - steps (any, optional, nullable)
  - created_at (string, required)
  - updated_at (string, required)
  - tx_hash (string, optional, nullable)
  - execution_mode (string, optional)
  - owner_address (string, optional)
  - plugs_hash (string, optional)
  - scheduler_status (string, optional)
  - last_error (string, optional)
  - verdict (string, optional)
  - failing_condition (integer, optional)
  - last_simmed_block (integer, optional)
  - outputs (any[], optional, nullable)
  - relay (object, optional, nullable)
    - typed_data (object, required)
      - types (Record<string, array>, required)
        - value (object[], required)
          - name (string, required)
          - type (string, required)
      - primaryType (string, required)
      - domain (Record<string, any>, required)
        - value (any, required)
      - message (Record<string, any>, required)
        - value (any, required)
    - plugs (string[], required)
    - state (string[], required)
    - manifest (object[], required)
      - token_in (string, required)
      - token_out (string, required)
      - amount_in (integer, required)
      - executor_slot (integer, required)
      - route_slot (integer, required)

Example:

```
POST https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/transaction/
```

### Compile transaction

`PUT https://api.plug.to/transaction/`

Compiles a draft action sequence into coil options, output manifests, and simulated slot values without persisting anything.

This 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.

Reach 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.

Reference: https://plug.to/docs/compile-transaction/

Query parameters:

- input[chain_id] (integer, required) — The chain to compile the transaction for.
- input[owner] (string, optional) — 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.
- input[steps] (string, required) — The steps/actions to compile.
- input[overrides] (string, optional) — 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.
- input[signature] (string, optional) — 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.
- input[deadline] (integer, optional) — 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.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object, optional, nullable)
  - options (Record<string, array>[], optional, nullable)
    - value (object[], required)
      - name (string, required)
      - type (string, required)
      - ref (string, required)
  - outputs (any[], optional, nullable)
  - parameters (object[], optional, nullable) — Inputs the draft leaves unbound for execution time.
    - step (integer, required)
    - name (string, required)
    - type (string, required)
  - graph (object, optional, nullable)
    - nodes (object[], required)
      - step (integer, required)
      - protocol (string, required)
      - action (string, required)
      - outputs (any[], optional, nullable)
      - ir (object[], optional, nullable)
        - index (integer, required)
        - kind (string, required)
        - label (string, optional, nullable)
        - dead (boolean, optional, nullable)
        - reads (integer[], optional, nullable)
        - writes (integer[], optional, nullable)
    - edges (object[], required)
      - kind (string, required)
      - source (integer, required)
      - source_slot (integer, required)
      - source_name (string, optional, nullable)
      - source_tags (any, optional, nullable)
      - fields (integer[], optional, nullable)
      - target (integer, required)
      - target_input (string, required)
      - ref (string, required)
  - simulation (object, optional, nullable)
    - verdict (string, optional, nullable)
    - reason (string, optional, nullable)
    - failing_step (integer, optional, nullable)
    - gas_used (integer, optional, nullable)
    - block_number (integer, optional, nullable)
    - outputs (object[], optional, nullable)
      - action_index (integer, required)
      - action (string, required)
      - assumed (boolean, optional, nullable)
      - slots (object[], required)
        - name (string, required)
        - type (any, required)
        - slot (integer, required)
        - path (string, required)
        - tags (object[], optional, nullable)
          - kind (string, required)
          - value (string, optional)
          - qualifiers (string[], optional)
          - dynamic (boolean, optional)
          - reference (integer, optional)
        - value (string, optional, nullable)
    - exclusions (object[], optional, nullable)
      - step (integer, required)
      - cause (string, required)
  - calls (object[], optional, nullable) — The executable wallet_sendCalls batch. Present only when the request carried the owner's signature and the simulation verdict is executable.
    - to (string, required)
    - value (string, required)
    - data (string, required)
  - program (object, optional, nullable) — 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.
    - socket (string, required)
    - salt (string, required)
    - deadline (integer, required)
    - typed_data (object, required)
      - types (Record<string, array>, required)
        - value (object[], required)
          - name (string, required)
          - type (string, required)
      - primaryType (string, required)
      - domain (Record<string, any>, required)
        - value (any, required)
      - message (Record<string, any>, required)
        - value (any, required)

Example:

```
PUT https://api.plug.to/transaction/
```

### Submit transaction

`PUT https://api.plug.to/address/{address}/transaction/`

Broadcasts a signed intent bundle.

The 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.

Reach 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.

Reference: https://plug.to/docs/submit-transaction/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Request body:

- chain_id (integer, required)
- owner (string, required)
- salt (string, optional)
- plugs (string[], required)
- state (string[], required)
- signature (string, required)
- manifest (object[], required)
  - token_in (string, required)
  - token_out (string, required)
  - amount_in (integer, required)
  - executor_slot (integer, required)
  - route_slot (integer, required)

Response:

- transaction_hash (string, required)

Example:

```
PUT https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/transaction/
```

### Cancel transaction

`DELETE https://api.plug.to/address/{address}/transaction/`

Cancels a scheduled or pending intent owned by the address.

An 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.

Reach 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.

Reference: https://plug.to/docs/cancel-transaction/

Path parameters:

- address (string, required) — The EVM address to get information for. In the case that you request an address we have never indexed, we will immediately index it.

Query parameters:

- id (string, required) — The intent row id to cancel.

Response:

- id (string, required)
- status (string, required)
- scheduler_status (string, optional)
- execution_mode (string, optional)
- tx_hash (string, optional, nullable)

Example:

```
DELETE https://api.plug.to/address/0x62180042606624f02d8a130da8a3171e9b33894d/transaction/
```

## Chain

Configuration and metadata for every blockchain network Plug indexes and executes on.

### Get chain(s)

`GET https://api.plug.to/chain`

Returns the configuration and metadata of every blockchain network Plug indexes and executes on.

Each 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.

Reach 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.

Reference: https://plug.to/docs/get-chains/

Query parameters:

- filter[chain_id] (integer[], optional) — Filter results to specific chains from the listed of supported options.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object, optional, nullable)
  - chain_id (integer, required)
  - address (string, required)
  - name (string, required)
  - symbol (string, required)
  - decimals (integer, required)
  - icon (string, required)
  - external (Record<string, object>, required)
    - value (object, required)
      - name (string, required)
      - url (string, required)
  - block_time (integer, required)

Example:

```
GET https://api.plug.to/chain
```

## Authentication

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.

### Get nonce

`GET https://api.plug.to/auth/nonce`

Issues a one-time nonce to embed in a Sign-In with Ethereum message.

The 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.

Reach for it at the start of wallet authentication, put the value in the SIWE message, and send the signed result to the verify surface.

Reference: https://plug.to/docs/get-nonce/

Response:

- data (object, required)
  - nonce (string, required) — One-time value to embed in the SIWE message before signing.
  - expires_at (string, required) — RFC 3339 timestamp after which the nonce is rejected.

Example:

```
GET https://api.plug.to/auth/nonce
```

### Verify signature

`POST https://api.plug.to/auth/verify`

Exchanges a signed Sign-In with Ethereum message for an access and refresh token pair.

The 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.

Reach 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.

Reference: https://plug.to/docs/verify-signature/

Request body:

- message (string, required) — The exact SIWE message that was signed, verbatim.
- signature (string, required) — Hex signature of the SIWE message produced by the wallet.

Response:

- data (object, required)
  - access_token (string, required) — Bearer token for the Authorization header.
  - refresh_token (string, required) — Token used to rotate the pair once the access token expires.
  - expires_in (integer, required) — Access token lifetime in seconds from issuance.

Example:

```
POST https://api.plug.to/auth/verify
```

### Refresh token

`POST https://api.plug.to/auth/refresh`

Rotates an expiring access token using its refresh token.

Access 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.

Reach for it just before the access token expires, or on the first rejected request, and replace both stored tokens with what comes back.

Reference: https://plug.to/docs/refresh-token/

Request body:

- refresh_token (string, required) — The refresh token issued by /auth/verify or a prior refresh.

Response:

- data (object, required)
  - access_token (string, required) — Bearer token for the Authorization header.
  - refresh_token (string, required) — Token used to rotate the pair once the access token expires.
  - expires_in (integer, required) — Access token lifetime in seconds from issuance.

Example:

```
POST https://api.plug.to/auth/refresh
```

### Get session

`GET https://api.plug.to/auth/session`

Resolves the address that the presented access token authenticates.

It 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.

Reach 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.

Reference: https://plug.to/docs/get-session/

Response:

- data (object, required)
  - address (string, required) — The EVM address the presented access token authenticates.

Example:

```
GET https://api.plug.to/auth/session
```

## CDN

Derived presentation data for remote assets, such as the dominant color of a hosted image.

### Get color

`GET https://api.plug.to/cdn/{encoded_url}/color`

Returns the dominant color of a hosted image along with a text color that stays readable on top of it.

The 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.

Reach 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.

Reference: https://plug.to/docs/get-color/

Path parameters:

- encoded_url (string, required) — Base64url encoding of the absolute asset URL, the same segment the /cdn proxy serves the image from.

Headers:

- Accept (string, required, default application/json, one of application/json, text/event-stream) — 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.

Response:

- links (object, optional)
  - self (string, required)
  - prev (string, optional)
  - next (string, optional)
- headers (unknown, optional)
- data (object, optional, nullable)
  - color (string, required)
  - textColor (string, required)

Example:

```
GET https://api.plug.to/cdn/{encoded_url}/color
```