# tide API

> Sui data for apps and agents: assets (DAS layout), parsed transactions with plain-language explanations, full address history since genesis, wallets, coins, streams and webhooks. Every answer carries asOf, the index position it is true at.

## Base URLs

- REST: https://api.tide.ad/v0/... and https://api.tide.ad/v1/...
- JSON-RPC 2.0: POST https://api.tide.ad/ (also /rpc), batches up to 100
- MCP (streamable HTTP): https://api.tide.ad/mcp
- WebSocket: wss://api.tide.ad/ and SSE https://api.tide.ad/v1/stream

Credits are per call. Errors cost nothing. Replace YOUR_KEY with a key, or drop the api-key parameter to use the keyless tier.

## Assets

### getAsset

JSON-RPC getAsset

One asset: an NFT, kiosk item, SuiNS name, other object, or a coin type.

Returns the asset in DAS layout: content (name, image, traits), grouping (collection), royalty, creators, ownership (including kiosk and listing price), and a sui block with type, version, digest and display. Pass an object id for NFTs, kiosk items and SuiNS names, or a Move coin type for a coin (then token_info holds supply and the price with its time). Returns not_found when the object does not exist.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | params | Asset id: an object id (0x...) for NFTs, kiosk items and SuiNS names, or a Move coin type (0x2::sui::SUI) for a coin. |
| options | object | no | params | Optional flags. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getAsset","params":{"id":"0xae81a1f657fa67206d3de56546fb476a2726266e06ad8ae225cd8f161887c1e0"}}'
```

### getAssetBatch

JSON-RPC getAssetBatch

Up to 1,000 assets by id in one call.

Takes object ids and coin types (mixed is fine) and returns { items, asOf } with one entry per id in the same order, null where the id does not exist. Use it to enrich a list of ids from a transaction or wallet. The result is wrapped in an object so asOf can ride along. Costs 2 credits plus 1 per 10 ids.

Credits: varies. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| ids | array | yes | params | Object ids (0x...) and coin types (0x2::sui::SUI), at most 1,000. |
| options | object | no | params | Optional flags. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getAssetBatch","params":{"ids":["0xae81a1f657fa67206d3de56546fb476a2726266e06ad8ae225cd8f161887c1e0","0x2::sui::SUI"]}}'
```

### getAssetsByOwner

JSON-RPC getAssetsByOwner

Everything an address holds: NFTs (including those in its kiosks), SuiNS names and optionally coins.

Lists the NFTs and SuiNS names an address owns, including items sitting in the kiosks it controls through a KioskOwnerCap. Set options.showFungible to add its coins on the first page (summed per coin type, most valuable first, up to 100) and options.showNativeBalance to add the SUI balance with its USD value and price time. Set options.showZeroBalance to keep coins with a zero balance. Ownership is read from the NFT index, so the newest second of transfers may lag. Pages hold up to 100 items; use cursor to continue.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| ownerAddress | string | yes | params | Owner: a 0x address or a SuiNS name ending in .sui. |
| limit | integer | no | params | Items per page, 1 to 100 (each item carries its full traits). |
| cursor | string | no | params | Cursor from the previous response. Preferred over page. |
| page | integer | no | params | Page number, 1 to 10. tide maps it to a cursor. Use cursor for anything deeper. |
| sortBy | any | no | params | An object { sortBy, sortDirection }. sortBy: created, updated, recent_action, none (default order), or tide's price, rarity, listed, floor. sortDirection: asc or desc. |
| options | object | no | params | Optional flags. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getAssetsByOwner","params":{"ownerAddress":"0xb30ad69255009768b8f651f10f0055090b19783755ec2154d7fd9cf873f7dc47","limit":5,"options":{"showFungible":true,"showNativeBalance":true}}}'
```

### getAssetsByGroup

JSON-RPC getAssetsByGroup

The items of one collection.

Lists the items of a collection. groupKey is collection; groupValue is the Move struct type of the items (0x...::module::Name) or the collection slug. Items come with traits, listing price and rarity. Sort with sortBy price, rarity or listed. Returns not_found when no collection matches.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| groupKey | string (collection) | yes | params | Only collection is supported on Sui. |
| groupValue | string | yes | params | The collection's Move struct type or its slug. |
| limit | integer | no | params | Items per page, 1 to 100 (each item carries its full traits). |
| cursor | string | no | params | Cursor from the previous response. Preferred over page. |
| page | integer | no | params | Page number, 1 to 10. tide maps it to a cursor. Use cursor for anything deeper. |
| sortBy | any | no | params | An object { sortBy, sortDirection }. sortBy: created, updated, recent_action, none (default order), or tide's price, rarity, listed, floor. sortDirection: asc or desc. |
| options | object | no | params | Optional flags. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getAssetsByGroup","params":{"groupKey":"collection","groupValue":"0xb908f3c6fea6865d32e2048c520cdfe3b5c5bbcebb658117c41bad70f52b7ccc::popkins_nft::Popkins","limit":5}}'
```

### searchAssets

JSON-RPC searchAssets

Find assets by owner, collection, name, traits or kind.

Filters assets. Pass ownerAddress and/or grouping ["collection", type-or-slug]; with neither, only tokenType fungible with a name works (a coin search). name matches the item or coin name. traits is a list of { trait_type, value } and works with grouping (server side); with only an owner it filters inside each page. tokenType: nonFungible (default), fungible (an owner's coins, or a coin search by name), all (with an owner: coins on the first page plus NFTs). interface keeps SuiNFT, KioskItem, SuiNSName or Object. burnt true is not indexed yet.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| ownerAddress | string | no | params | Owner address or .sui name. |
| grouping | array | no | params | ["collection", "<Move type or slug>"]. |
| interface | string (SuiNFT, KioskItem, SuiNSName, Coin, Object) | no | params | Keep one asset interface. |
| tokenType | string (fungible, nonFungible, all) | no | params | Default nonFungible. |
| name | string | no | params | Match on the item name (or coin name or symbol for fungible). |
| traits | array | no | params | Trait filters. Values of one trait_type are alternatives; different types combine. |
| burnt | boolean | no | params | Only false (the default) is supported. |
| limit | integer | no | params | Items per page, 1 to 100 (each item carries its full traits). |
| cursor | string | no | params | Cursor from the previous response. Preferred over page. |
| page | integer | no | params | Page number, 1 to 10. tide maps it to a cursor. Use cursor for anything deeper. |
| sortBy | any | no | params | An object { sortBy, sortDirection }. sortBy: created, updated, recent_action, none (default order), or tide's price, rarity, listed, floor. sortDirection: asc or desc. |
| options | object | no | params | Optional flags. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"searchAssets","params":{"grouping":["collection","0xb908f3c6fea6865d32e2048c520cdfe3b5c5bbcebb658117c41bad70f52b7ccc::popkins_nft::Popkins"],"traits":[{"trait_type":"Skin","value":"Forest"}],"limit":5}}'
```

### getTransactionsForAsset

JSON-RPC getTransactionsForAsset (also getSignaturesForAsset)

Every transaction that changed an object, newest first.

Returns the object's version history from the index: for each version the transaction digest, checkpoint, timestamp, version, previous version, what happened (created, mutated, transferred, wrapped, unwrapped, deleted), the new owner and the address that sent it. The history is complete from the first indexed checkpoint; older objects return not_indexed with the lowest checkpoint available. Page with cursor. getSignaturesForAsset is an alias that returns the same rows. Link a digest to getTransaction for the parsed transaction.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | params | Object id (0x...) of the NFT, kiosk item, SuiNS name or any other object. |
| limit | integer | no | params | Versions per page. |
| cursor | string | no | params | Cursor from the previous response. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getTransactionsForAsset","params":{"id":"0xae81a1f657fa67206d3de56546fb476a2726266e06ad8ae225cd8f161887c1e0","limit":5}}'
```

### getKiosk

JSON-RPC getKiosk

A kiosk: who controls it, what is in it, and what is listed at what price.

Returns the kiosk's controlling address (the holder of its KioskOwnerCap), the cap id, profits, and a page of its items. Each item has its id (pass it to getAsset for full details), type, name, image, whether it is locked, and its listing when listed: the price a buyer pays in SUI with USD and its price time, and the venue (kiosk, Tradeport and so on). limit counts kiosk entries per page (an item can use up to three entries: item, lock, listing), so pages may hold fewer items than limit. Continue with cursor.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | params | Kiosk object id (0x...). |
| limit | integer | no | params | Kiosk entries per page. |
| cursor | string | no | params | Cursor from the previous response. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getKiosk","params":{"id":"0x57086347a30d901959121b754afe961c475541636ab2b98001ef11503c8b5509"}}'
```

### kiosk.policies

GET /v1/kiosk/policies/:type

Transfer policies and rules (royalty, kiosk lock, floor price) for an NFT type.

Returns the TransferPolicy objects that govern sales of an NFT type, with the rules each one enforces and the SUI balance it holds. Decoded rules are royalty (basis points and minimum in MIST), kiosk lock, personal kiosk and floor price. Rules from other packages are listed by their Move type with the raw config. Use it before listing or buying an NFT to know the fees and conditions. A type with no policy returns not_found.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Full Move type of the NFT, like 0x...::module::Name. URL-encode it in the path. |

```sh
curl "https://api.tide.ad/v1/kiosk/policies/0x541023fc967e97500b68d08b20d4b00178ce66bc54b81baa15bac3a6faf41d0e::gem::Gem?api-key=YOUR_KEY"
```

## Transactions

### tx.parse

POST /v0/transactions

Parse up to 100 transaction digests into typed, described transactions.

Send transaction digests and get back one TideTransaction each: type, source protocol, a plain-English description, SUI and coin transfers, balance changes, object changes, events, commands and an insight block (price impact, sandwich detection). The reply is a bare array in request order; digests tide does not have are left out. Amounts are raw integers with decimal-adjusted twins, SUI in MIST. Costs 1 credit per transaction returned.

Credits: varies. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| transactions | array | yes | body | Transaction digests, 1 to 100. |

```sh
curl -X POST "https://api.tide.ad/v0/transactions?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"transactions":["3nrSJ85TEooEfeXjbbDEVdsbebfYdFMXzHE3gBSHTkcT","2hhr9HKTRS7vnqc6r9ny7WQgecSzTnkAbPwrpGACKCE7"]}'
```

### getTransaction

JSON-RPC getTransaction

One parsed transaction by digest.

Returns one TideTransaction (type, source, description, transfers, balance changes, object changes, events, commands, explain, insight) with an asOf field, or null when the digest is unknown. Pass [digest] or { digest }. 1 credit. For the unparsed node shape use getTransactionBlock.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| digest | string | yes | params | Base58 transaction digest. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getTransaction","params":{"digest":"3nrSJ85TEooEfeXjbbDEVdsbebfYdFMXzHE3gBSHTkcT"}}'
```

### getTransactionBlock

JSON-RPC getTransactionBlock

The raw transaction as the Sui node reports it.

Returns the executed transaction in the node's own shape: transaction data with inputs and commands, effects with changed objects and gas, events, balance changes and signatures. Use it when you need the exact on-chain record. Early history can lack some detail; the partial field says so. Pass [digest] or { digest }. 1 credit. Use getTransaction for the parsed view.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| digest | string | yes | params | Base58 transaction digest. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getTransactionBlock","params":{"digest":"3nrSJ85TEooEfeXjbbDEVdsbebfYdFMXzHE3gBSHTkcT"}}'
```

## History

### tx.history

GET /v0/addresses/:address/transactions

Parsed transaction history of an address, filterable by type, source, time and checkpoint.

Returns parsed transactions that involve an address (sender, sponsor, balance change, object owner, package call or event sender), newest first by default, as a bare array. The address may be a 0x address or a SuiNS name. Page with before=<last digest>, or with until for the other direction. Type and source filters classify transactions while paging: one call reads at most 10 index pages. If it finds fewer than limit matches it returns what it found with a continuation (a digest in the x-tide-next header for the REST path, paginationToken for the others) and capped true in the RPC result. Time filters are exact at checkpoint granularity. History older than the loaded index returns not_indexed with the lowest checkpoint available. 10 credits per page.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | path | 0x address or .sui name. |
| type | string (TRANSFER, SWAP, ARBITRAGE, FLASH_LOAN, LIQUIDATION, DEPOSIT, WITHDRAW, BORROW, REPAY, STAKE, UNSTAKE, MINT, BURN, NFT_SALE, NFT_LISTING, NFT_TRANSFER, PUBLISH, UPGRADE, ORACLE_UPDATE, CONTRACT_CALL, SYSTEM, UNKNOWN) | no | query | One of TRANSFER, SWAP, ARBITRAGE, FLASH_LOAN, LIQUIDATION, DEPOSIT, WITHDRAW, BORROW, REPAY, STAKE, UNSTAKE, MINT, BURN, NFT_SALE, NFT_LISTING, NFT_TRANSFER, PUBLISH, UPGRADE, ORACLE_UPDATE, CONTRACT_CALL, SYSTEM, UNKNOWN. The type comes from tide's transaction classifier: a DEX trade is SWAP, a loop that ends in the coin it started with is ARBITRAGE, an NFT purchase is NFT_SALE. |
| source | string | no | query | Protocol slug, for example CETUS. |
| before | string | no | query | Digest. Only transactions older than this one. |
| until | string | no | query | Digest. Only transactions newer than this one (stop here). Alias: after. |
| limit | integer | no | query | Transactions per page, 1 to 100. Default 10. |
| gte-time | integer | no | query | Unix seconds, at or after. |
| gt-time | integer | no | query | Unix seconds, after. |
| lte-time | integer | no | query | Unix seconds, at or before. |
| lt-time | integer | no | query | Unix seconds, before. |
| gte-checkpoint | integer | no | query | Checkpoint, at or after. Alias gte-slot. |
| gt-checkpoint | integer | no | query | Checkpoint, after. |
| lte-checkpoint | integer | no | query | Checkpoint, at or before. |
| lt-checkpoint | integer | no | query | Checkpoint, before. |
| sort | string (asc, desc) | no | query | Order. |
| status | string (succeeded, failed, any) | no | query | Filter by outcome. Default any. |
| coinType | string | no | query | Only transactions that changed this coin's balance for the address. |
| direction | string (in, out) | no | query | With coinType or alone: only inflows or outflows for the address, gas excluded. |

```sh
curl "https://api.tide.ad/v0/addresses/0xffd4f043057226453aeba59732d41c6093516f54823ebc3a16d17f8a77d2f0ad/transactions?limit=5&api-key=YOUR_KEY"
```

### getTransactionsForAddress

JSON-RPC getTransactionsForAddress

Full history of an address with sort order, filters and a pagination token.

Returns an address's transactions as digest rows (default, up to 1,000 per call) or full parsed transactions (up to 100). Sort oldest first or newest first, filter by checkpoint (alias slot), checkpoint time, status, type, source, coin type, direction and role, and continue with paginationToken ("checkpoint:txIndex"). Pass params as [address, config] or as one object. Result: { data, paginationToken, asOf }. Digest rows are { digest, checkpoint, txIndex, timestamp, status } plus type and source when a type or source filter is set. Type and source filters classify transactions while paging: one call reads at most 10 index pages. If it finds fewer than limit matches it returns what it found with a continuation (a digest in the x-tide-next header for the REST path, paginationToken for the others) and capped true in the RPC result. Time filters are exact at checkpoint granularity. History below the loaded index returns not_indexed with the lowest checkpoint. 10 credits per 100 full transactions, 10 per page of digest rows.

Credits: varies. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | params | 0x address or .sui name. |
| transactionDetails | string (signatures, full) | no | params | signatures (digest rows, default) or full. |
| sortOrder | string (asc, desc) | no | params | asc is oldest first, desc newest first (default). |
| limit | integer | no | params | Up to 1000 for digest rows (signatures), 100 for full. Default 100. |
| paginationToken | string | no | params | Token "checkpoint:txIndex" from the previous page. |
| filters | object | no | params | Filters. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getTransactionsForAddress","params":{"address":"0xffd4f043057226453aeba59732d41c6093516f54823ebc3a16d17f8a77d2f0ad","transactionDetails":"signatures","limit":5,"filters":{"status":"succeeded"}}}'
```

### bridge.transfers

GET /v1/wallet/:wallet/bridge

Sui Bridge transfers of a wallet, out of Sui and into Sui, newest first.

Lists the Sui Bridge transfers a wallet made out of Sui (deposits, with the Ethereum address that receives them) and the transfers that were claimed into it (with the Ethereum sender when the claim shows it). Each item has the direction, coin, amount in whole coins and raw units, USD at the time of the transfer, the other chain, the other side's address, the status (deposited, approved by the validator committee, or claimed), the digest and the time. Transfers out of Sui are listed with status deposited or approved. Claims of wrapped SUI that came back from Ethereum are listed only when the claim names the coin. Accepts a 0x address, a name.sui or an @name.

Credits: 3. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| limit | integer | no | query | Items per page, 1 to 100. Default 25. |
| cursor | string | no | query | Opaque cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/wallet/0xfe3b1d3fc6fb639c9f283cbc005345ec91bc94efdac6d2f79addd73d1de1d771/bridge?limit=5&api-key=YOUR_KEY"
```

## Wallet

### wallet.balances

GET /v1/wallet/:wallet/balances

Every coin a wallet holds now, with USD value, sorted by value.

Returns the wallet's live coin balances. Each balance has coinType (also given as mint), symbol, decimals, balance in whole coins, balanceRaw in the smallest unit, pricePerToken, usdValue and priceAsOf. Priced coins come first, sorted by usdValue, then unpriced coins by balance. A page holds up to 100 coins: use page, or cursor from the response. totalUsdValue adds up every priced coin the wallet holds, not only this page. Each balance has priceStatus: priced, unpriced (no market that counts) or pending (its price was still being read when the request's time ran out). When any coin is pending, totalUsdValue is null and pricing is "partial": read again shortly for the full total; a total is never given without them. Partial answers are not cached. showNfts adds a short NFT list. The wallet can be an address, name.sui or @name.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| page | integer | no | query | Page number, starting at 1. Default 1. |
| limit | integer | no | query | Coins per page, up to 100. Default 100. |
| cursor | string | no | query | Cursor from the previous response (same as page). |
| showZeroBalance | boolean | no | query | Include coins held with a zero balance. Default false. |
| showNative | boolean | no | query | Include SUI. Default true. |
| showNfts | boolean | no | query | Add an nfts list (first 50 items). Default false. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/balances?limit=10&api-key=YOUR_KEY"
```

### wallet.nfts

GET /v1/wallet/:wallet/nfts

NFTs and kiosk items a wallet holds now.

Returns the NFTs the wallet owns, including items held in its kiosks, as assets in the same layout as getAssetsByOwner (interface, content, grouping, ownership). Use limit and page to walk the list, or cursor from the response. The wallet can be an address, name.sui or @name. Coins are not included: use /balances for those.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| page | integer | no | query | Page number, starting at 1. |
| limit | integer | no | query | Items per page, default 50. |
| cursor | string | no | query | Cursor from the previous response. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/nfts?limit=5&api-key=YOUR_KEY"
```

### wallet.balanceAt

GET /v1/wallet/:wallet/balance-at

A wallet's balance of one coin at a past time or checkpoint.

Returns the exact balance of one coin at the end of a given checkpoint, found by adding up every balance change of the wallet and coin up to that point. Pass the coin as coinType (alias mint) and exactly one of time (unix seconds), datetime or checkpoint (alias slot). balance is in whole coins and balanceRaw in the smallest unit. asOf names the last transaction that changed the balance at or before the point, or is null when the balance was zero. History covers all of Sui since genesis. The wallet can be an address, name.sui or @name.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| coinType | string | no | query | Coin type such as 0x2::sui::SUI. Alias: mint. |
| mint | string | no | query | Alias of coinType. |
| time | integer | no | query | Point in time as unix seconds. Give exactly one of time, datetime or checkpoint. |
| datetime | string | no | query | Point in time as an ISO 8601 date, UTC when no zone is given, for example 2025-01-10 19:20:00. |
| checkpoint | integer | no | query | Checkpoint sequence number. Alias: slot. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/balance-at?coinType=0x2%3A%3Asui%3A%3ASUI&datetime=2026-11-01+00%3A00%3A00&api-key=YOUR_KEY"
```

### wallet.holdingsAt

GET /v1/wallet/:wallet/holdings-at

Every coin a wallet held at a past time, with USD at that time.

Returns all coin balances of a wallet at the end of a checkpoint, plus the total portfolio value on that date. A coin is priced at that time only if it traded in a pool with at least $1,000 of liquidity then, or is a stablecoin or a major coin; its value is capped at what that pool could have paid for the whole balance. Other coins have null price and priceAsOf and add nothing to totalUsdValue. Items are sorted by USD value, then by raw balance, and paged with cursor. Pass exactly one of time, datetime or checkpoint. One call covers the whole wallet.

Credits: 20. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| time | integer | no | query | Point in time as unix seconds. Give exactly one of time, datetime or checkpoint. |
| datetime | string | no | query | Point in time as an ISO 8601 date, UTC when no zone is given, for example 2025-01-10 19:20:00. |
| checkpoint | integer | no | query | Checkpoint sequence number. Alias: slot. |
| limit | integer | no | query | Coins per page, default 100. |
| cursor | string | no | query | Cursor from the previous page. |
| showZeroBalance | boolean | no | query | Not used: only coins with a balance are listed. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/holdings-at?datetime=2026-11-01+00%3A00%3A00&limit=10&api-key=YOUR_KEY"
```

### wallet.history

GET /v1/wallet/:wallet/history

A wallet's transactions with its balance changes, all history, both directions.

Returns the wallet's transactions, newest first or oldest first (sort), each with the digest, checkpoint, timestamp (unix seconds), fee in SUI, feePayer, error and the wallet's own balanceChanges per coin (amount in whole coins, amountRaw in the smallest unit). A transaction is included when the wallet sent it, paid its gas, or had a balance change. Page with cursor, up to 100 per page. Filter by time, checkpoint, coinType, status and type (coarse: TRANSFER, CONTRACT_CALL, PUBLISH, UPGRADE, SYSTEM). For fully parsed transactions use /v0/addresses/{address}/transactions.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| limit | integer | no | query | Rows per page, up to 100. |
| cursor | string | no | query | Cursor from the previous page. Alias: before (history). |
| sort | string (desc, asc) | no | query | desc is newest first (default), asc is oldest first. |
| gte-time | integer | no | query | Only transactions at or after this unix time (seconds). |
| lte-time | integer | no | query | Only transactions at or before this unix time (seconds). |
| gte-checkpoint | integer | no | query | Only transactions at or after this checkpoint. |
| lte-checkpoint | integer | no | query | Only transactions at or before this checkpoint. |
| coinType | string | no | query | Only transactions that changed this coin's balance for the wallet. Alias: mint. |
| before | string | no | query | Alias of cursor. |
| status | string (success, failed) | no | query | Only successful or only failed transactions. |
| type | string (TRANSFER, CONTRACT_CALL, PUBLISH, UPGRADE, SYSTEM) | no | query | Coarse transaction type filter. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/history?limit=5&api-key=YOUR_KEY"
```

### wallet.transfers

GET /v1/wallet/:wallet/transfers

A wallet's coin transfers in and out with the counterparty.

Returns the coin transfers of a wallet: one record per coin moved, with direction (in or out), counterparty, coinType (also mint), symbol, amount in whole coins, amountRaw and decimals. Only plain transfers count: transactions whose commands are built-in transfers and payments, not swaps or protocol calls (use /history for those). Gas is not part of the amount. Page with cursor; a page covers up to limit transactions and may hold a few more records when one transaction moves several coins. Filter by direction, coinType and time.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| limit | integer | no | query | Rows per page, up to 100. |
| cursor | string | no | query | Cursor from the previous page. Alias: before (history). |
| sort | string (desc, asc) | no | query | desc is newest first (default), asc is oldest first. |
| gte-time | integer | no | query | Only transactions at or after this unix time (seconds). |
| lte-time | integer | no | query | Only transactions at or before this unix time (seconds). |
| gte-checkpoint | integer | no | query | Only transactions at or after this checkpoint. |
| lte-checkpoint | integer | no | query | Only transactions at or before this checkpoint. |
| coinType | string | no | query | Only transactions that changed this coin's balance for the wallet. Alias: mint. |
| direction | string (in, out) | no | query | Only incoming or only outgoing transfers. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/transfers?limit=5&api-key=YOUR_KEY"
```

### wallet.identity

GET /v1/wallet/:wallet/identity

Who a wallet is: known label and SuiNS names.

Returns the label tide knows for a wallet (exchange, bot, named wallet) and every SuiNS name it owns as { address, name, category, type, tags } plus suiNames. Returns 404 when the wallet has no label and no SuiNS name. The wallet can be an address, name.sui or @name. Use batch-identity for many wallets at once.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |

```sh
curl "https://api.tide.ad/v1/wallet/0x935029ca5219502a47ac9b69f556ccf6e2198b5e7815cf50f68846f723739cbd/identity?api-key=YOUR_KEY"
```

### wallet.batchIdentity

POST /v1/wallet/batch-identity

Identity of up to 100 wallets in one call.

Takes { addresses: [...] } with up to 100 entries, each an address, name.sui or @name, and returns one identity per entry in the same order. An entry that came from a name carries inputDomain. A name that does not resolve comes back in place as { address: null, type: "unknown", inputDomain, unresolved: true }. Wallets with no label are returned with type unknown. Batch lookups use the default SuiNS name only: call identity for the full list of names.

Credits: varies. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| addresses | array | yes | body | Up to 100 addresses, name.sui or @name values. |

```sh
curl -X POST "https://api.tide.ad/v1/wallet/batch-identity?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"addresses":["0x935029ca5219502a47ac9b69f556ccf6e2198b5e7815cf50f68846f723739cbd","@nobody-here-xyz"]}'
```

### wallet.fundedBy

GET /v1/wallet/:wallet/funded-by

Who first sent SUI to a wallet.

Returns the first inbound SUI transfer the wallet ever received from another wallet: the funder with its label and SuiNS name when known, the amount, the transaction digest and the time. Staking rewards and the wallet's own moves do not count. Returns 404 when no such transfer exists.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |

```sh
curl "https://api.tide.ad/v1/wallet/0x671f7079e238edf837ae8d4fe8274f3337e1b20bbc08e2e9b9b7f5fcee9566e2/funded-by?api-key=YOUR_KEY"
```

### wallet.pnl

GET /v1/wallet/:wallet/pnl

Realized and unrealized profit and loss per coin for a wallet.

Returns one row per coin the wallet traded, with realized, unrealized and total profit in USD and the traded volume. Values come from the wallet's swaps and are marked at current prices. Realized, unrealized and total are null when they cannot be worked out for a coin. Sort with sort (realized, total, volume, trades) and dir, page with cursor, search a coin with q.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| sort | string (realized, total, volume, trades) | no | query | Sort key, default realized. |
| dir | string (asc, desc) | no | query | Sort direction, default desc. |
| q | string | no | query | Filter coins by symbol or name. |
| cursor | string | no | query | Cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/wallet/0x935029ca5219502a47ac9b69f556ccf6e2198b5e7815cf50f68846f723739cbd/pnl?sort=volume&api-key=YOUR_KEY"
```

### wallet.positions

GET /v1/wallet/:wallet/positions

A wallet's DeFi positions: liquidity, lending, staking and vaults.

Returns the open DeFi positions of a wallet with the protocol, the kind (liquidity, lending, staked, vault, borrow), the coins in and out, USD value and APY when known. Values are marked at current prices. totals adds up value and borrowed USD.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |

```sh
curl "https://api.tide.ad/v1/wallet/0x935029ca5219502a47ac9b69f556ccf6e2198b5e7815cf50f68846f723739cbd/positions?api-key=YOUR_KEY"
```

### wallet.linked

GET /v1/wallet/:wallet/linked

Wallets that look related to this one.

Returns wallets funded from the same source that each traded real volume, with their realized profit and volume when known, and the combined numbers for the group. This is a hint from funding links, not proof of one owner.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |

```sh
curl "https://api.tide.ad/v1/wallet/0x935029ca5219502a47ac9b69f556ccf6e2198b5e7815cf50f68846f723739cbd/linked?api-key=YOUR_KEY"
```

### address.kind

GET /v1/address/:address/kind

What a Sui address is: key scheme, zkLogin, multisig, passkey, object or package.

Answers what is behind an address. Key addresses come back as ed25519, secp256k1, secp256r1, passkey, zklogin (issuer, address seed, key id) or multisig (every member with scheme, public key, address and weight, plus the threshold). Object ids come back as object or package, and an address that never signed comes back as unknown. The kind is read from the signature of the latest transaction the address signed, so details need at least one signed transaction. The result also lists, for each regulated coin the address holds, whether the address is on the deny list this epoch and next epoch. Accepts a 0x address, a name.sui or an @name.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | path | Address or object id (0x...), a name.sui or an @name. |

```sh
curl "https://api.tide.ad/v1/address/0x935029ca5219502a47ac9b69f556ccf6e2198b5e7815cf50f68846f723739cbd/kind?api-key=YOUR_KEY"
```

## Coins and markets

### coins.get

GET /v1/coins/:type

One coin: metadata, supply, price, market cap, volume, liquidity, holders and who holds the TreasuryCap.

Returns the coin's name, symbol, decimals and icon, total and circulating supply, the USD price with its time (with lowLiquidity: true when it is the last trade of a coin with no pool of $1,000 or more; market cap and fully diluted value are null then), market cap, fully diluted value, 24 hour volume and liquidity (each USD value as { usd, priceAsOf }), the holder count, who published it and when, and the control summary (field authority): whether the TreasuryCap can still mint more, whether the deny list can block addresses, and whether the metadata can still change. Amounts are decimal numbers with the raw integer beside them (amountRaw). Use it first when you need to know what a coin is.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Move coin type, URL-encoded in the path, for example 0x2::sui::SUI or 0xdeeb7a46...::deep::DEEP. |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP?api-key=YOUR_KEY"
```

### coins.prices

POST /v1/prices

USD prices for up to 100 coins, now or at a past time.

Send coinTypes (up to 100 Move types) and get one row per type in the same order: usd and priceAsOf, which is the time of the price. A coin with a pool holding at least $1,000 of liquidity (at that time, for at), a live bonding curve or a major market gets its price. A coin that trades without such a pool gets its last trade price with lowLiquidity: true; treat that price as indicative, since the pool cannot absorb a real sale. Any other coin returns usd null and priceAsOf null. Pass at (unix seconds or an ISO date) for the price at that time from the trade history; the live price is the default. Costs 1 credit per 10 coins.

Credits: varies. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| coinTypes | array | yes | body | Move coin types, at most 100. |
| at | string | no | body | Optional: unix seconds or ISO date for a past price. Omit for the live price. |

```sh
curl -X POST "https://api.tide.ad/v1/prices?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"coinTypes":["0x2::sui::SUI","0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP","0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC"]}'
```

### coins.candles

GET /v1/coins/:type/candles

OHLCV candles for a coin at 1 second to 1 week intervals.

Returns candles oldest first: time (unix seconds, the candle's open), open, high, low, close in USD at that candle, and volumeUsd. interval is one of 1s, 1m, 5m, 15m, 1h, 4h, 1d, 1w (1s covers only the last five minutes). Bound the range with from and to (unix seconds or ISO). When more candles exist than limit, cursor is set; pass it back as cursor to continue into the past.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Move coin type, URL-encoded in the path, for example 0x2::sui::SUI or 0xdeeb7a46...::deep::DEEP. |
| interval | string (1s, 1m, 5m, 15m, 1h, 4h, 1d, 1w) | no | query | Candle size. |
| from | string | no | query | Earliest candle: unix seconds or ISO date. |
| to | string | no | query | Latest candle: unix seconds or ISO date. Default now. |
| limit | integer | no | query | Most candles to return (the newest in range). |
| cursor | string | no | query | Cursor from the previous response; continues into the past. |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/candles?interval=1h&limit=24&api-key=YOUR_KEY"
```

### coins.holders

GET /v1/coins/:type/holders

Top holders of a coin, ranked by balance, with the USD value of each.

Returns holders largest first: rank, owner (address, SuiNS name, label when known), balance as amount and amountRaw, pctSupply, value { usd, priceAsOf }, and kind (wallet, pool, lending and so on). Balances include staked, LP and lending positions; wallet parts are read from chain. The first 100 holders are served from a cached list so any limit works there; later pages hold 100 each. For holders at a past time use coins.holdersAt.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Move coin type, URL-encoded in the path, for example 0x2::sui::SUI or 0xdeeb7a46...::deep::DEEP. |
| limit | integer | no | query | Rows per page within the first 100 holders. |
| cursor | string | no | query | Cursor from the previous response. |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/holders?limit=10&api-key=YOUR_KEY"
```

### coins.trades

GET /v1/coins/:type/trades

Recent DEX trades of a coin, newest first.

Returns on-chain swaps: digest, timestamp, side (buy or sell), trader, amount of the coin, the price at that trade in USD, the trade's value in USD, and the venues used. Each USD value is priced at the trade's own time, which is its timestamp. Page back with cursor. Exchange trades are not mixed in. Link a digest to getTransaction for the full parsed transaction.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Move coin type, URL-encoded in the path, for example 0x2::sui::SUI or 0xdeeb7a46...::deep::DEEP. |
| limit | integer | no | query | Trades per page. |
| cursor | string | no | query | Cursor from the previous response (the time of the oldest trade seen). |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/trades?limit=10&api-key=YOUR_KEY"
```

### coins.pools

GET /v1/coins/:type/pools

The busiest liquidity pools for a coin, with TVL and 24 hour volume.

Returns the pools that traded this coin most over the last 7 days: pool object id, name, venue, fee tier in percent, TVL and 24 hour volume (each as { usd, priceAsOf }), and 24 hour trade and trader counts. Use the object id with getAsset or objects.get to inspect a pool.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Move coin type, URL-encoded in the path, for example 0x2::sui::SUI or 0xdeeb7a46...::deep::DEEP. |
| limit | integer | no | query | Most pools to return. |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/pools?api-key=YOUR_KEY"
```

### coins.security

GET /v1/coins/:type/security

Launch safety for a coin: TreasuryCap and deny list status, honeypot flag, and a list of checks.

Returns a level (ok, warn or danger), one plain word for it, the control facts (field authority: can more be minted through the TreasuryCap, can the deny list block addresses, can the metadata change, who holds each cap) and the list of checks, each with a key, a level and a sentence. Also honeypot and flagged. Use it before an agent buys or lists a new coin. The checks are read from chain and trade data; they are signals, not a guarantee.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Move coin type, URL-encoded in the path, for example 0x2::sui::SUI or 0xdeeb7a46...::deep::DEEP. |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/security?api-key=YOUR_KEY"
```

### markets.top

GET /v1/markets

Ranked coin lists: trending, top, new, gainers, losers, bonding and graduated.

Returns coins for one list over one window: trending, top (by volume), new, gainers, losers, bonding (still on a launch curve) or graduated. Each row has price { usd, priceAsOf }, change over 5 minutes, 1, 6 and 24 hours, market cap, 24 hour volume, liquidity, holders, creation time, a verified flag and a risk level with chips. window is 5m, 1h, 6h or 24h. Pass cursor to page.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| list | string (trending, top, new, gainers, losers, bonding, graduated) | no | query | Which list. |
| window | string (5m, 1h, 6h, 24h) | no | query | Window for change and the ranking. |
| cursor | string | no | query | Cursor from the previous response. |

```sh
curl "https://api.tide.ad/v1/markets?list=top&window=24h&api-key=YOUR_KEY"
```

### coins.holdersAt

GET /v1/coins/:type/holders-at

The top holders of a coin at a past time or checkpoint.

Returns the largest holders of a coin at the end of a checkpoint, found by adding up every balance change of the coin per owner. Pass exactly one of time, datetime or checkpoint. It works for coins with up to about 5 million balance changes before that point; bigger coins such as SUI or USDC are refused with invalid_params until the daily holder snapshots ship (phase 2). Each holder carries its share of the supply held by wallets at that point. Use /v1/coins/{type}/holders for the live list.

Credits: 25. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | yes | path | Coin type such as 0x...::mod::NAME. |
| time | integer | no | query | Point in time as unix seconds. Give exactly one of time, datetime or checkpoint. |
| datetime | string | no | query | Point in time as an ISO 8601 date, UTC when no zone is given, for example 2025-01-10 19:20:00. |
| checkpoint | integer | no | query | Checkpoint sequence number. Alias: slot. |
| limit | integer | no | query | Holders to return, default 50. |

```sh
curl "https://api.tide.ad/v1/coins/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270::deep::DEEP/holders-at?datetime=2026-10-01+00%3A00%3A00&limit=10&api-key=YOUR_KEY"
```

## Chain

### objects.get

GET /v1/objects/:id

One object: type, owner, version and fields as they are now.

Returns the current state of an object: type, version, digest, owner (address, object, shared, immutable), the Move fields as JSON, the Display values and the storage rebate in MIST. For a deleted or wrapped object it returns status deleted or wrapped with the last version the index saw. Use /history for every past version. Packages are served by /v1/packages/{id}.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Object id (0x...). |

```sh
curl "https://api.tide.ad/v1/objects/0x0000000000000000000000000000000000000000000000000000000000000006?api-key=YOUR_KEY"
```

### objects.history

GET /v1/objects/:id/history

Every version of an object since it was created, either direction.

Returns the object's versions with the kind of change (created, mutated, transferred, wrapped, unwrapped, deleted), the owner after the change, the transaction digest and time, and the sender. Newest first by default, oldest first with sort=asc. Page with cursor, up to 200 versions. coinBalance is the raw balance for coin objects. Contents of past versions are not stored: this is the version log, not a state snapshot. Same data as getTransactionsForAsset but one row per version.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Object id (0x...). |
| sort | string (desc, asc) | no | query | desc is newest first (default). |
| limit | integer | no | query | Versions per page, default 50. |
| cursor | string | no | query | Cursor from the previous page (a version number). |

```sh
curl "https://api.tide.ad/v1/objects/0x0000000000000000000000000000000000000000000000000000000000000006/history?limit=5&api-key=YOUR_KEY"
```

### events.list

GET /v1/events

Move events by type or package in any time or checkpoint range.

Returns decoded Move events, newest first or oldest first, for one event type (type, with or without type parameters) or for everything a package emitted (package, optionally with module). Narrow with sender, fromTime and toTime (unix seconds) or fromCheckpoint and toCheckpoint. Each event has its transaction digest, checkpoint, time and the decoded JSON. Page with cursor, up to 200 per page. Pass type or package, not both. Covers all of history since genesis.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| type | string | no | query | Event type, for example 0x2::coin::CurrencyCreated or a full generic instance. Give type or package. |
| package | string | no | query | Package id: all events emitted by that package. |
| module | string | no | query | With package: only events from this module. |
| sender | string | no | query | Only events sent by this address. |
| fromTime | integer | no | query | Unix seconds, inclusive. |
| toTime | integer | no | query | Unix seconds, inclusive. |
| fromCheckpoint | integer | no | query | First checkpoint, inclusive. |
| toCheckpoint | integer | no | query | Last checkpoint, inclusive. |
| sort | string (desc, asc) | no | query | desc is newest first (default). |
| limit | integer | no | query | Events per page, default 50. |
| cursor | string | no | query | Cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/events?type=0x2%3A%3Acoin%3A%3ACurrencyCreated&limit=3&api-key=YOUR_KEY"
```

### checkpoints.get

GET /v1/checkpoints/:seq

One checkpoint: header, gas and its transactions.

Returns a checkpoint by sequence number, or the latest one with seq=latest. It has the digest, previous digest, epoch, time (unix seconds), transaction count, network transaction total, the gas totals in MIST, the neighbouring checkpoint numbers and a list of its transactions (digest, sender, type, status, a one-line sentence). System transactions are counted in system and left out of the list. Older than the index starts: not_indexed with the lowest checkpoint available.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| seq | string | yes | path | Checkpoint sequence number, or latest. |

```sh
curl "https://api.tide.ad/v1/checkpoints/341000000?api-key=YOUR_KEY"
```

### epochs.list

GET /v1/epochs

Epochs, newest first, with gas price and transaction counts.

Returns epochs newest first: epoch number, start and end time (unix seconds, end is null for the current epoch), checkpoint count, transaction count, the reference gas price in MIST, gas fees, stake rewards and the storage fund in MIST. Page back with cursor. Use it for staking and fee history.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| limit | integer | no | query | Epochs per page, default 20. |
| cursor | string | no | query | Cursor from the previous page: return epochs older than this epoch number. |

```sh
curl "https://api.tide.ad/v1/epochs?limit=3&api-key=YOUR_KEY"
```

### validators.list

GET /v1/validators

The active validator set with stake, voting power, APY and commission.

Returns the active validators of the current epoch, ranked by stake: address, name, stake in MIST, voting power percent, estimated APY percent, commission percent and next epoch commission, the gas price each quoted, and whether it is in the supermajority group that holds a third of voting power. Use it for staking choices and network health.

Credits: 1. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/validators?api-key=YOUR_KEY"
```

### packages.get

GET /v1/packages/:id

A Move package: versions, modules, functions and dependencies.

Returns a package by any of its version ids: the original id, current version, publisher, publish and upgrade times (unix seconds), the version list with digests and checkpoints, dependencies, and each module with its public functions (name, visibility, entry flag, signature) and struct names. The UpgradeCap is reported so you can see who can upgrade it.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Package id (0x...), any version. |

```sh
curl "https://api.tide.ad/v1/packages/0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270?api-key=YOUR_KEY"
```

### names.resolve

GET /v1/names/:name

Resolve a SuiNS name to the address it points at.

Returns the target address of a SuiNS name (name.sui or @name), the id of the name's NFT, its expiry time (unix seconds) and whether it has expired. Returns 404 when the name is not registered. Names are lower case.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| name | string | yes | path | SuiNS name such as adeniyi.sui, or @adeniyi. |

```sh
curl "https://api.tide.ad/v1/names/adeniyi.sui?api-key=YOUR_KEY"
```

### names.reverse

GET /v1/names/reverse/:address

The SuiNS names of an address.

Returns the default (reverse) SuiNS name of an address and every name the address owns. Returns 404 when the address has neither. The address can be a 0x address, name.sui or @name.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | path | 0x address, name.sui or @name. |

```sh
curl "https://api.tide.ad/v1/names/reverse/0x1eb7c57e3f2bd0fc6cb9dcffd143ea957e4d98f805c358733f76dee0667fe0b1?api-key=YOUR_KEY"
```

### search

GET /v1/search

Find coins, names, packages, collections, addresses, objects and transactions.

Searches by free text or by id: a coin symbol or type, a SuiNS name, a package or module name, a validator, a collection, a 0x address or object id, a transaction digest, a checkpoint number. Returns ranked hits, each with a kind, title, id, a short subtitle and a link on tide.ad. interpretedAs says how the query was read. Use it to turn a name into an id before calling another method.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| q | string | yes | query | Search text or id, up to 300 characters. |
| limit | integer | no | query | Hits to return, default 20. |

```sh
curl "https://api.tide.ad/v1/search?q=deepbook&limit=5&api-key=YOUR_KEY"
```

## Simulate

### tx.simulate

POST /v1/tx/simulate

Check a transaction before signing: what it would do, what it would cost, or why it would fail.

Runs a transaction against the chain's current state without signing or sending it, and explains what would happen: success or failure, balance changes per address with USD, objects created, changed or deleted, events, gas in MIST and SUI, values returned by each command and one plain sentence. Use it before signing, and as a read-only call: a Move call that returns a value shows it in commandResults. Send txBytes (what a wallet is about to sign) or sender plus a JSON programmable transaction block, with optional gasBudget and gasPrice. On failure it names the package, module and function, the abort code and the error constant when the module names its errors, and also explains out of gas, short balances and missing or stale objects in plain words. 10 credits.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| txBytes | string | no | body | The unsigned TransactionData as base64, the bytes a wallet is about to sign. When it has no gas payment, tide selects gas coins for the sender. |
| sender | string | no | body | 0x address that would sign. Required with transaction. |
| transaction | object|string | no | body | A programmable transaction block as JSON, the output of Transaction.toJSON() in the Sui TypeScript SDK. Object inputs may be bare ids: tide resolves versions from the chain. |
| gasBudget | string | no | body | Gas budget in MIST. Left out, tide measures the gas and adds a 25 percent margin. |
| gasPrice | string | no | body | Gas price in MIST per unit. Left out, the reference gas price of the current epoch is used. |

```sh
curl -X POST "https://api.tide.ad/v1/tx/simulate?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"sender":"0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270","transaction":{"version":2,"sender":"0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270","expiration":null,"gasData":{"budget":null,"price":null,"owner":null,"payment":null},"inputs":[{"Pure":{"bytes":"QEIPAAAAAAA="}},{"Pure":{"bytes":"3ut6RmLuyfLz3vA/uTemY93aouIVuAeKKE0Ca3lGwnA="}}],"commands":[{"SplitCoins":{"coin":{"GasCoin":true},"amounts":[{"Input":0}]}},{"TransferObjects":{"objects":[{"NestedResult":[0,0]}],"address":{"Input":1}}}]}}'
```

### simulateTransaction

JSON-RPC simulateTransaction

Check a transaction before signing: what it would do, what it would cost, or why it would fail.

Runs a transaction against the chain's current state without signing or sending it, and explains what would happen: success or failure, balance changes per address with USD, objects created, changed or deleted, events, gas in MIST and SUI, values returned by each command and one plain sentence. Use it before signing, and as a read-only call: a Move call that returns a value shows it in commandResults. Send txBytes (what a wallet is about to sign) or sender plus a JSON programmable transaction block, with optional gasBudget and gasPrice. On failure it names the package, module and function, the abort code and the error constant when the module names its errors, and also explains out of gas, short balances and missing or stale objects in plain words. 10 credits. Pass one params object.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| txBytes | string | no | params | The unsigned TransactionData as base64, the bytes a wallet is about to sign. When it has no gas payment, tide selects gas coins for the sender. |
| sender | string | no | params | 0x address that would sign. Required with transaction. |
| transaction | object|string | no | params | A programmable transaction block as JSON, the output of Transaction.toJSON() in the Sui TypeScript SDK. Object inputs may be bare ids: tide resolves versions from the chain. |
| gasBudget | string | no | params | Gas budget in MIST. Left out, tide measures the gas and adds a 25 percent margin. |
| gasPrice | string | no | params | Gas price in MIST per unit. Left out, the reference gas price of the current epoch is used. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"simulateTransaction","params":{"sender":"0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270","transaction":{"version":2,"sender":"0xdeeb7a4662eec9f2f3def03fb937a663dddaa2e215b8078a284d026b7946c270","expiration":null,"gasData":{"budget":null,"price":null,"owner":null,"payment":null},"inputs":[{"Pure":{"bytes":"QEIPAAAAAAA="}},{"Pure":{"bytes":"3ut6RmLuyfLz3vA/uTemY93aouIVuAeKKE0Ca3lGwnA="}}],"commands":[{"SplitCoins":{"coin":{"GasCoin":true},"amounts":[{"Input":0}]}},{"TransferObjects":{"objects":[{"NestedResult":[0,0]}],"address":{"Input":1}}}]}}}'
```

## Objects and fields

### objects.at

GET /v1/objects/:id/at

An object as it was at a version, checkpoint or time, with its contents.

Returns the object's state at one point: pass exactly one of version, checkpoint, time (unix seconds) or datetime (ISO, UTC). The answer says whether the object existed, was deleted or was wrapped then, and for an existing object gives the version, digest, type, owner and Move fields as JSON, plus the checkpoint and transaction that wrote that version. With checkpoint or time you get the version that was live at that point. Object contents are available from checkpoint 330677000; before that the call returns not_indexed, and /history still lists the versions. Answers for past points never change.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Object id (0x...). |
| version | integer | no | query | Exact object version. Use /history to list versions. |
| checkpoint | integer | no | query | Checkpoint sequence number: the version live after that checkpoint. |
| time | integer | no | query | Unix seconds: the version live at that time. |
| datetime | string | no | query | ISO 8601 date and time, UTC, for example 2026-10-01T12:00:00Z. |

```sh
curl "https://api.tide.ad/v1/objects/0x0000000000000000000000000000000000000000000000000000000000000006/at?checkpoint=341000000&api-key=YOUR_KEY"
```

### objects.dynamicFields

GET /v1/objects/:id/dynamic-fields

The dynamic fields of an object, with decoded names and values.

Lists the dynamic fields and dynamic object fields stored under an object or under a table, bag or other UID, with the key and the value decoded as JSON. Each item has a kind (field or object), the key type and value, the value type, the field object id and, for dynamic object fields, the child object id (read it with /v1/objects/{id}). Up to 100 per page; pass the cursor to continue. Values are current, not historical.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Parent object id, or the id of a table, bag or other UID (0x...). |
| limit | integer | no | query | Fields per page, default 50. |
| cursor | string | no | query | Cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/objects/0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407/dynamic-fields?limit=5&api-key=YOUR_KEY"
```

### objects.tree

GET /v1/objects/:id/tree

Everything an object holds: dynamic fields, tables, wrapped structs and kiosk items.

Walks down from an object and returns its children as a tree: dynamic fields and dynamic object fields, tables and bags, and structs wrapped inside its contents (found by their UID). Depth defaults to 2 and goes up to 3. Each level shows at most 50 children, and a node says moreChildren with a cursor for /dynamic-fields when it was cut; total work is capped too and the top level sets truncated when anything was left out. For a kiosk the answer also lists its items with listing price in MIST and lock state. Values are current, not historical.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Object id (0x...). |
| depth | integer | no | query | Levels to walk down, default 2. |

```sh
curl "https://api.tide.ad/v1/objects/0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407/tree?depth=2&api-key=YOUR_KEY"
```

## Packages

### packages.abi

GET /v1/packages/:id/abi

The full Move interface of a package: modules, functions, structs, enums and events.

Returns every module of one package id with its functions (visibility, entry flag, type parameters with constraints, parameters and returns as readable Move types such as &mut 0x2::coin::Coin<T0>), its structs and enums (abilities, fields with types) and the events the package emits. TxContext parameters are dropped because the chain adds them. Events are the structs the module bytecode passes to event::emit; if the bytecode listing is unavailable they are the event-like structs (copy and drop) and eventsSource says so. A package id is immutable, so the answer never changes; use packages.versions to see other versions.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Package id (0x...), one specific version. |

```sh
curl "https://api.tide.ad/v1/packages/0x2c8d603bc51326b8c13cef9dd07031a408a48dddb541963357661df5d3204809/abi?api-key=YOUR_KEY"
```

### packages.versions

GET /v1/packages/:id/versions

Every version of a package with publisher, time and the modules each upgrade added or removed.

Lists each version of the package family that the given id belongs to, with the version's package id, publish or upgrade digest, checkpoint, time (unix seconds), the address that sent it, its modules and the modules added or removed against the previous version. Any version id works as input. Version 1 is the publish, later versions are upgrades. Time, sender and digest come from the index and are null for a version it has not seen.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Package id (0x...), any version of the family. |
| order | string (asc, desc) | no | query | Version order. Default desc (newest first). |
| limit | integer | no | query | Versions per page. Default 50. |
| cursor | string | no | query | Opaque cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/packages/0x2c8d603bc51326b8c13cef9dd07031a408a48dddb541963357661df5d3204809/versions?limit=10&api-key=YOUR_KEY"
```

### packages.usage

GET /v1/packages/:id/usage

How a package is used: calls per day, per function, unique senders, failure rate and events.

Counts the transactions that called any version of the package in the last 24h (hourly buckets), 7d or 30d (UTC days, the current day included). Total calls, failures and the series are exact. Calls per function (top 20), unique senders and events per type are exact for quiet packages and scaled from a uniform sample for busy ones; the sampled field says which. Unique senders is a floor when sampled. Cached for 5 minutes.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Package id (0x...), any version. All versions of the family are counted. |
| window | string (24h, 7d, 30d) | no | query | Window. Default 24h. |

```sh
curl "https://api.tide.ad/v1/packages/0x2c8d603bc51326b8c13cef9dd07031a408a48dddb541963357661df5d3204809/usage?window=24h&api-key=YOUR_KEY"
```

### packages.callers

GET /v1/packages/:id/callers

The top senders that call a package, with call counts, last call time and success rate.

Returns the addresses that sent the most transactions calling any version of the package in the window, with the call count, share of all calls, last call time (unix seconds) and success rate. For quiet packages the answer is exact. For busy ones it comes from a uniform sample of transactions: counts are scaled up, last call is the latest sampled one, and the sampled field says so. Cached for 5 minutes.

Credits: 10. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Package id (0x...), any version. All versions of the family are counted. |
| window | string (24h, 7d, 30d) | no | query | Window. Default 24h. |
| limit | integer | no | query | Senders to return. Default 20. |

```sh
curl "https://api.tide.ad/v1/packages/0x2c8d603bc51326b8c13cef9dd07031a408a48dddb541963357661df5d3204809/callers?window=24h&limit=10&api-key=YOUR_KEY"
```

### packages.howToCall

GET /v1/packages/:id/functions/:module/:function/call

How to call one Move function from a PTB: parameters explained, a TypeScript snippet and a JSON PTB.

Explains each parameter of a Move function: a plain value or an object, a reference or by value, a well-known shared object such as the Clock at 0x6, and which type arguments to fill. TxContext is left out because the chain adds it. Returns a ready TypeScript snippet using Transaction.moveCall from @mysten/sui, a JSON PTB skeleton in the SDK v2 shape with placeholders, and whether a PTB can call the function at all (public or entry) with the reason if not.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Package id (0x...), the version whose function you want to call. |
| module | string | yes | path | Module name, for example coin. |
| function | string | yes | path | Function name, for example split. |

```sh
curl "https://api.tide.ad/v1/packages/0x2/functions/coin/split/call?api-key=YOUR_KEY"
```

## Staking

### wallet.stakes

GET /v1/wallet/:wallet/stakes

A wallet's staked SUI: validator, status and rewards so far.

Returns the StakedSui and FungibleStakedSui objects the wallet owns, largest principal first, 100 per page with a cursor. Each stake has the object id, the validator (address, name, image), the principal in MIST, the activation epoch and a status: pending until its activation epoch starts, then active. Rewards so far are the pool tokens bought at the activation epoch rate valued at the current epoch rate, minus the principal; they are an estimate until you withdraw. Totals come in MIST, SUI and USD with the price time. Stakes in a pool whose validator left the set show validator null and no rewards. The wallet can be an address, name.sui or @name.

Credits: 3. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Wallet address (0x...), name.sui or @name. |
| limit | integer | no | query | Stakes per page, default 100. Totals always cover every stake the wallet holds. |
| cursor | string | no | query | cursor from the previous page, to get the next one. |

```sh
curl "https://api.tide.ad/v1/wallet/0x4fffd0005522be4bc029724c7f0f6ed7093a6bf3a09b90e62f61dc15181e1a3e/stakes?api-key=YOUR_KEY"
```

### validators.history

GET /v1/validators/:address/history

One validator across epochs: stake, voting power, commission, gas price, rewards, APY.

Returns one row per epoch, newest first, for a validator address. Each row has the stake and voting power at that epoch, commission in basis points, the gas price it quoted, the staking rewards it earned in MIST, its name and the APY for the epoch. APY is the pool exchange rate growth over the epoch, annualised with the real length of that epoch. Page back with cursor, which is an epoch number. An address that was never a validator returns not_found.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | path | The validator's Sui address (0x...). |
| limit | integer | no | query | Epochs per page, default 30. |
| cursor | string | no | query | Cursor from the previous page: return epochs older than this epoch number. |

```sh
curl "https://api.tide.ad/v1/validators/0x4fffd0005522be4bc029724c7f0f6ed7093a6bf3a09b90e62f61dc15181e1a3e/history?limit=5&api-key=YOUR_KEY"
```

## Order books

### books.list

GET /v1/books

Every DeepBook v3 pool with its coins, book parameters, best prices and 24 hour activity.

Returns all DeepBook v3 order book pools on Sui. Each pool has its object id, base and quote coin (type, symbol, decimals), tick size in quote per base, lot size and minimum size in base units, taker and maker fee in basis points, best bid, best ask and mid price, and 24 hour volume and trade count from fill events. Prices and sizes are decimal numbers, not raw integers. Pools with an empty side have a null mid price. Volume fields are null if the history index is busy. Cached for 45 seconds.

Credits: 2. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/books?api-key=YOUR_KEY"
```

### books.depth

GET /v1/books/:pool/depth

Live bids and asks of one DeepBook pool, with mid price and spread.

Reads the current order book of a DeepBook v3 pool straight from the chain with a read-only call, no signature needed. Returns up to levels price levels on each side (default 20, at most 100): bids from the highest price down and asks from the lowest up, each with the decimal price (quote per base) and the total size in base coin. Also returns the best bid, best ask, mid price, spread and spread in basis points. Cached for 1 second.

Credits: 3. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| pool | string | yes | path | Pool object id (0x...). List them with books.list. |
| levels | integer | no | query | Price levels per side, default 20. |

```sh
curl "https://api.tide.ad/v1/books/0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407/depth?levels=10&api-key=YOUR_KEY"
```

### books.trades

GET /v1/books/:pool/trades

Recent fills of one DeepBook pool, newest first.

Returns fills of a DeepBook v3 pool from its OrderFilled events, newest first, 50 per page by default and at most 200. Each fill has the decimal price (quote per base), base size, quote size, which side the taker was on (buy or sell), the maker and taker balance manager and order id, the time and the transaction digest. Pass the cursor of the previous page to go further back. A page can hold fewer rows than limit with a cursor still set when the pool was quiet in the part of history that was searched: keep following the cursor until it is null.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| pool | string | yes | path | Pool object id (0x...). List them with books.list. |
| limit | integer | no | query | Fills per page, default 50. |
| cursor | string | no | query | Cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/books/0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407/trades?limit=10&api-key=YOUR_KEY"
```

### wallet.orders

GET /v1/wallet/:wallet/orders

A wallet's DeepBook balance managers with their balances, open orders and recent fills.

Finds the DeepBook v3 balance managers owned by the wallet, then returns for each one the coins it holds, its open orders across all pools and the fills where it was maker or taker. Open orders carry decimal price, quantity, filled and remaining size in base coin, side (bid or ask), status and expiry time. Fills are newest first, 20 per page by default, with a cursor for older ones. Balances are the free balances inside the manager, not funds locked in resting orders. Accepts an address or a name.sui.

Credits: 5. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Owner address (0x...), a name.sui or an @name. |
| limit | integer | no | query | Fills per page, default 20. |
| cursor | string | no | query | Fills cursor from the previous page. |

```sh
curl "https://api.tide.ad/v1/wallet/0xb5c5d547340849ac4f12c43f91f8321d0c5e76f0b25442fffae79d4e119fd928/orders?limit=10&api-key=YOUR_KEY"
```

## Walrus

### walrus.blob

GET /v1/walrus/blobs/:blobId

One Walrus blob: size, epochs, expiry, deletable flag, owner and status.

Looks up a Walrus blob by its blob id and returns what is stored on Sui about it: size, encoding, the registered and certified epochs, the storage start and end epoch, an estimated end date, whether it is deletable, the owner and a status. The blob id can be the base64url form Walrus uses, its u256 decimal, or the Blob object id. If the same blob id was registered more than once, the newest registration is returned and the other object ids are listed in otherObjects. Status is deleted when the Blob object is gone and the index saw a delete.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| blobId | string | yes | path | Blob id as base64url (43 characters) or u256 decimal, or the 0x Blob object id. |

```sh
curl "https://api.tide.ad/v1/walrus/blobs/0xcaa7c10b88a25af15bcad1ef9999e790c97b243a973a17e31cd68819664d5b6a?api-key=YOUR_KEY"
```

### walrus.blobs

GET /v1/wallet/:wallet/walrus-blobs

Walrus blobs a wallet owns, with epochs, size and expiry.

Lists the Walrus Blob objects owned by an address, with the same fields as the single blob lookup. The wallet can be a 0x address, a name.sui or an @name. Results come from the chain as it is now, in the order the chain returns them. Page with cursor; each page is up to limit blobs. Blobs held inside a kiosk or another object are not listed.

Credits: 2. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| wallet | string | yes | path | Owner: a 0x address, a name.sui or an @name. |
| cursor | string | no | query | Cursor from the previous page. |
| limit | integer | no | query | Blobs per page, 1 to 200. |

```sh
curl "https://api.tide.ad/v1/wallet/0xbfaadd8980b532c65ca09be4fdc9901c5ccafc1814f035502e526288aefd092f/walrus-blobs?limit=5&api-key=YOUR_KEY"
```

## SQL

### sql.execute

POST /v1/sql/execute (also /api/v1/sql/execute)

Run a SQL query over all of Sui

Starts a run of one SQL SELECT over the public tables (every transaction, event, object version and balance change since genesis, about a second behind the chain) and returns an execution_id. Poll /v1/execution/{execution_id}/status, then read /v1/execution/{execution_id}/results. Credits are charged when the run ends: 20 plus 1 per 50 MB read; a reused result (max_age) costs 2. Without a key, runs come out of the small daily keyless allowance.

Credits: varies. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| dialect | string (tide, trino) | no | body | tide (default), or trino for Trino SQL written against the standard Sui table names; it is translated before it runs. |
| sql | string | yes | body | One SQL SELECT over the public tables. Use {{name}} for parameters. 0x ids (64 hex) can be compared directly: WHERE sender = 0x1a2b... |
| params | object | no | body | Values for {{name}} parameters: { name: value } or { name: { type: text / number / date / list, value } }. |
| max_age | integer | no | body | Reuse a finished result of the same SQL and params up to this many seconds old (costs 2 credits). Default 0, always run. |
| wait_ms | integer | no | body | Wait up to this many milliseconds (max 30000) for the run to finish and return its status in the same response. |

```sh
curl -X POST "https://api.tide.ad/v1/sql/execute?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"sql":"SELECT sequence_number, block_time, total_transaction_blocks FROM sui.checkpoints ORDER BY sequence_number DESC LIMIT 5"}'
```

### sql.status

GET /v1/execution/:execution_id/status (also /api/v1/execution/:execution_id/status)

Status of a SQL run

State of a run (QUERY_STATE_PENDING, QUERY_STATE_EXECUTING, QUERY_STATE_COMPLETED, QUERY_STATE_FAILED, QUERY_STATE_CANCELLED), its timings, result size, rows and bytes read, credits, and as_of: the checkpoint the data was at when it ran. A failed run has error.message with metadata.line and metadata.column. Pass wait_ms (max 30000) to wait for the run to finish.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| execution_id | string | yes | path |  |
| wait_ms | integer | no | query |  |

```sh
curl "https://api.tide.ad/v1/execution/01019A4C0F2A8B3C4D5E6F708192A3B4C5/status?api-key=YOUR_KEY"
```

### sql.results

GET /v1/execution/:execution_id/results (also /api/v1/execution/:execution_id/results)

Results of a SQL run

Rows of a finished run with result.metadata (column names and types, row count, timings) and as_of. Page with limit (default 1000, max 100000) and offset; next_uri points at the next page. Pick columns with columns=a,b and sort with sort_by="col desc". rows=array returns each row as an array in column order. Before the run finishes this returns its status with result null.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| execution_id | string | yes | path |  |
| limit | integer | no | query |  |
| offset | integer | no | query |  |
| columns | string | no | query |  |
| sort_by | string | no | query |  |
| rows | string (object, array) | no | query |  |
| wait_ms | integer | no | query |  |

```sh
curl "https://api.tide.ad/v1/execution/01019A4C0F2A8B3C4D5E6F708192A3B4C5/results?limit=100&api-key=YOUR_KEY"
```

### sql.results_csv

GET /v1/execution/:execution_id/results/csv (also /api/v1/execution/:execution_id/results/csv)

Results of a SQL run as CSV

The full result of a finished run as CSV with a header row. Ids print as 0x hex.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| execution_id | string | yes | path |  |

```sh
curl "https://api.tide.ad/v1/execution/01019A4C0F2A8B3C4D5E6F708192A3B4C5/results/csv?api-key=YOUR_KEY"
```

### sql.cancel

POST /v1/execution/:execution_id/cancel (also /api/v1/execution/:execution_id/cancel)

Cancel a SQL run

Stops a pending or running run started by the same key, session or IP. A cancelled run costs nothing.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| execution_id | string | yes | path |  |

```sh
curl -X POST "https://api.tide.ad/v1/execution/01019A4C0F2A8B3C4D5E6F708192A3B4C5/cancel?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### sql.schema

GET /v1/sql/schema

The public SQL tables and columns

Every public table with its columns and types, grouped by namespace (sui, dex, prices, nft, lending, launchpad, labels, suins, validators, staking, walrus and more). The same list the editor's schema browser shows.

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/sql/schema?api-key=YOUR_KEY"
```

### sql.translate

POST /v1/sql/translate (also /api/v1/sql/translate)

Trino SQL to tide SQL

Translates a query written in the Trino dialect for the standard Sui table names into the tide SQL that runs here, without running it. dbt/jinja wrappers are stripped, 0x ids are padded to 32 bytes and {{name}} parameters are kept. Errors come back as invalid_params with line and column when known.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| sql | string | yes | body | One SELECT in Trino SQL. |

```sh
curl -X POST "https://api.tide.ad/v1/sql/translate?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"sql":"SELECT date_trunc('day', from_unixtime(timestamp_ms / 1000)) AS day, count(*) AS txs FROM sui.transactions WHERE sender = 0x2 GROUP BY 1"}'
```

### sql.limits

GET /v1/sql/limits

Your SQL limits

The caller's plan limits for SQL: runs at once, queue depth, time limit, bytes and rows a run may read, result rows, how long results are kept, and the engine's current load.

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/sql/limits?api-key=YOUR_KEY"
```

### sql.pulse

GET /v1/sql/pulse

Live numbers for Sui

The latest indexed checkpoint and how far behind the chain it is, transactions per second now and the 1 hour peak, total transactions since genesis, active wallets and transactions today, SUI staked, the storage fund, live Walrus blobs and DEX volume. Refreshed every second (fast numbers) and every minute (the rest). Free, no key.

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/sql/pulse?api-key=YOUR_KEY"
```

### query.create

POST /v1/query (also /api/v1/query)

Save a query

Saves a SQL query with its parameters and visualizations under your account and returns its query_id. Queries are public unless is_private is true. Needs a login or an API key.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| name | string | no | body |  |
| description | string | no | body |  |
| query_sql | string | no | body | The SQL (also accepted as sql). |
| dialect | string (tide, trino) | no | body |  |
| query_parameters | array | no | body | [{ key, type: text / number / date / list, value, options? }] |
| visualizations | array | no | body | [{ id, type, name, config }] |
| tags | array | no | body |  |
| is_private | boolean | no | body |  |

```sh
curl -X POST "https://api.tide.ad/v1/query?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"name":"Latest checkpoints","query_sql":"SELECT sequence_number, block_time FROM sui.checkpoints ORDER BY sequence_number DESC LIMIT 10"}'
```

### query.get

GET /v1/query/:query_id (also /api/v1/query/:query_id)

A saved query

A saved query: name, description, owner, SQL, parameters with defaults, visualizations, stars, forks and its latest execution_id. Private queries are visible to their owner only.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| query_id | integer | yes | path |  |

```sh
curl "https://api.tide.ad/v1/query/1?api-key=YOUR_KEY"
```

### query.update

PUT /v1/query/:query_id (also /api/v1/query/:query_id, /v1/query/:query_id/update, /api/v1/query/:query_id/update)

Update a saved query

Changes any of name, description, query_sql, dialect, query_parameters, visualizations, tags, is_private or is_archived. Owner only. PUT, or POST to /v1/query/{query_id}/update.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| name | string | no | body |  |
| description | string | no | body |  |
| query_sql | string | no | body | The SQL (also accepted as sql). |
| dialect | string (tide, trino) | no | body |  |
| query_parameters | array | no | body | [{ key, type: text / number / date / list, value, options? }] |
| visualizations | array | no | body | [{ id, type, name, config }] |
| tags | array | no | body |  |
| is_private | boolean | no | body |  |
| query_id | integer | yes | path |  |
| is_archived | boolean | no | body |  |

```sh
curl -X PUT "https://api.tide.ad/v1/query/1?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"name":"Renamed"}'
```

### query.fork

POST /v1/query/:query_id/fork (also /api/v1/query/:query_id/fork)

Fork a query

Copies a public query (or your own) into your account and returns the new query. The original's fork count goes up by one.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| query_id | integer | yes | path |  |

```sh
curl -X POST "https://api.tide.ad/v1/query/1/fork?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### query.star

POST /v1/query/:query_id/star

Star or unstar a query

Stars a query (on: true, the default) or removes your star (on: false). Returns the star count.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| query_id | integer | yes | path |  |
| on | boolean | no | body |  |

```sh
curl -X POST "https://api.tide.ad/v1/query/1/star?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### query.list

GET /v1/queries

Browse saved queries

Public queries sorted by trending (stars, forks, views and runs this week), new, top or updated. Filter by owner (address), q (text in name, description or tags) or starred=1 (what you starred). Pages with limit and offset.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| sort | string (trending, new, top, updated) | no | query |  |
| owner | string | no | query |  |
| q | string | no | query |  |
| starred | string | no | query |  |
| limit | integer | no | query |  |
| offset | integer | no | query |  |

```sh
curl "https://api.tide.ad/v1/queries?sort=trending&limit=10&api-key=YOUR_KEY"
```

### query.execute

POST /v1/query/:query_id/execute (also /api/v1/query/:query_id/execute)

Run a saved query

Runs a saved query with its saved parameter defaults, overridden by query_parameters ({ name: value } or [{ key, value }]). Returns an execution_id to poll like sql.execute; with wait_ms (max 30000) it waits and returns the status. Credits are charged to the caller: 20 plus 1 per 50 MB read; max_age reuses a recent identical run for 2.

Credits: varies. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| query_id | integer | yes | path |  |
| query_parameters | object | no | body |  |
| max_age | integer | no | body |  |
| wait_ms | integer | no | body |  |
| performance | string | no | body |  |

```sh
curl -X POST "https://api.tide.ad/v1/query/1/execute?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### query.results

GET /v1/query/:query_id/results (also /api/v1/query/:query_id/results)

Latest results of a saved query

The rows of the most recent finished run of a saved query, without running it, in the same shape as /v1/execution/{execution_id}/results (limit, offset, columns, sort_by, rows=array). 404 when it has never finished a run.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| query_id | integer | yes | path |  |
| limit | integer | no | query |  |
| offset | integer | no | query |  |
| columns | string | no | query |  |
| sort_by | string | no | query |  |
| rows | string | no | query |  |

```sh
curl "https://api.tide.ad/v1/query/1/results?api-key=YOUR_KEY"
```

### dashboard.create

POST /v1/dashboard

Create a dashboard

Creates a dashboard of saved-query visualizations, text and section widgets with shared filters, a theme and a refresh schedule. Needs a login or an API key.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| name | string | no | body |  |
| slug | string | no | body |  |
| description | string | no | body |  |
| widgets | array | no | body | [{ id, kind: viz / text / section, query_id, viz_id, text, title, link?, x, y, w, h }] on a 12 column grid. A section may carry link: { label, href } shown beside its title. |
| params | array | no | body | Shared filters: [{ key, type: text / number / date / list, value, options?, label? }]. A filter applies to every widget whose query has a parameter with the same key. |
| theme | string (dark, light) | no | body |  |
| refresh_sec | integer | no | body | Re-run every widget's query this often (10 s to 7 days, 0 = never). Short schedules run while someone is viewing. |
| tags | array | no | body |  |
| links | array | no | body | Up to 4 outward links shown in the header: [{ label, href }], href a full https URL. |
| is_private | boolean | no | body |  |

```sh
curl -X POST "https://api.tide.ad/v1/dashboard?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"name":"My dashboard","widgets":[]}'
```

### dashboard.get

GET /v1/dashboard/:dashboard

A dashboard with its results

A dashboard with its widgets, filters, each widget's saved query and visualizations, and each query's latest results inline (up to 5,000 rows), so it renders complete at once. as_of on each result says which checkpoint it reflects.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| dashboard | string | yes | path | Slug or numeric id. |

```sh
curl "https://api.tide.ad/v1/dashboard/sui-pulse?api-key=YOUR_KEY"
```

### dashboard.update

PUT /v1/dashboard/:dashboard (also /v1/dashboard/:dashboard/update)

Update a dashboard

Changes any of name, slug, description, widgets, params, theme, refresh_sec, tags, is_private or is_archived. Owner only. PUT, or POST to /v1/dashboard/{dashboard}/update.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| name | string | no | body |  |
| slug | string | no | body |  |
| description | string | no | body |  |
| widgets | array | no | body | [{ id, kind: viz / text / section, query_id, viz_id, text, title, link?, x, y, w, h }] on a 12 column grid. A section may carry link: { label, href } shown beside its title. |
| params | array | no | body | Shared filters: [{ key, type: text / number / date / list, value, options?, label? }]. A filter applies to every widget whose query has a parameter with the same key. |
| theme | string (dark, light) | no | body |  |
| refresh_sec | integer | no | body | Re-run every widget's query this often (10 s to 7 days, 0 = never). Short schedules run while someone is viewing. |
| tags | array | no | body |  |
| links | array | no | body | Up to 4 outward links shown in the header: [{ label, href }], href a full https URL. |
| is_private | boolean | no | body |  |
| dashboard | string | yes | path |  |
| is_archived | boolean | no | body |  |

```sh
curl -X PUT "https://api.tide.ad/v1/dashboard/my-dashboard?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"name":"Renamed"}'
```

### dashboard.fork

POST /v1/dashboard/:dashboard/fork

Fork a dashboard

Copies a dashboard into your account (widgets keep pointing at the same saved queries; fork a query to change its SQL).

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| dashboard | string | yes | path | Slug or numeric id. |

```sh
curl -X POST "https://api.tide.ad/v1/dashboard/sui-pulse/fork?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### dashboard.star

POST /v1/dashboard/:dashboard/star

Star or unstar a dashboard

Stars a dashboard (on: true, the default) or removes your star (on: false). Returns the star count.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| dashboard | string | yes | path | Slug or numeric id. |
| on | boolean | no | body |  |

```sh
curl -X POST "https://api.tide.ad/v1/dashboard/sui-pulse/star?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### dashboard.run

POST /v1/dashboard/:dashboard/run

Run a dashboard with filter values

Runs every widget's query with the dashboard's filters set to params ({ key: value }) and returns { query_id: execution_id }; poll each like sql.execute. Identical runs from the last max_age seconds (default 60) are reused for 2 credits; new runs cost 20 plus 1 per 50 MB read, charged to the caller.

Credits: varies. Rate class: heavy.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| dashboard | string | yes | path | Slug or numeric id. |
| params | object | no | body |  |
| max_age | integer | no | body |  |

```sh
curl -X POST "https://api.tide.ad/v1/dashboard/sui-pulse/run?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"params":{}}'
```

### dashboard.list

GET /v1/dashboards

Browse dashboards

Public dashboards sorted by trending (featured first, then stars, forks and views this week), new or top. Filter by owner (address), q (text), starred=1 or featured=1. Pages with limit and offset.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| sort | string (trending, new, top) | no | query |  |
| owner | string | no | query |  |
| q | string | no | query |  |
| starred | string | no | query |  |
| featured | string | no | query |  |
| limit | integer | no | query |  |
| offset | integer | no | query |  |

```sh
curl "https://api.tide.ad/v1/dashboards?featured=1&api-key=YOUR_KEY"
```

## Gas

### getGasPriceEstimate

JSON-RPC getGasPriceEstimate

Gas price levels from recent transactions, optionally for given shared objects.

Returns the reference gas price of the current epoch (the lowest price a transaction can pay) and gas price percentiles over the last lookbackCheckpoints checkpoints: min, low (p25), medium (p50), high (p75), veryHigh (p95) and unsafeMax (p99), all in MIST per computation unit. Pass objectIds (shared objects such as a hot pool) to measure only transactions that touched them, which shows congestion on that object. gasPriceEstimate is the level you ask for with level (default medium), never below the reference price.

Credits: 1. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| objectIds | array | no | params | Up to 10 shared object ids. Only transactions that changed one of them are sampled. |
| lookbackCheckpoints | integer | no | params | How many recent checkpoints to sample, default 150 (about one minute). |
| level | string (min, low, medium, high, veryHigh, unsafeMax) | no | params | Which level gasPriceEstimate reports, default medium. |

```sh
curl -X POST "https://api.tide.ad/?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"getGasPriceEstimate","params":{"objectIds":["0x0000000000000000000000000000000000000000000000000000000000000006"],"lookbackCheckpoints":100}}'
```

## Account and keys

### auth.nonce

POST /v0/auth/nonce

Start a sign-in: get a message to sign with a Sui key.

Returns a one-time nonce and the exact message to sign. Sign `message` as a Sui personal message with the key of `address`, then send the signature to POST /v0/auth/verify (developer portal session) or POST /v0/keys/agent (a Free API key in one step). The nonce works once and expires after 5 minutes. Costs nothing.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | body | The Sui address that will sign (0x + 64 hex). |

```sh
curl -X POST "https://api.tide.ad/v0/auth/nonce?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"address":"0x7d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169677c1be02aaf0b58e"}'
```

### auth.verify

POST /v0/auth/verify

Finish sign-in: trade a signature for a 30-day session token.

Checks the signature over the message from POST /v0/auth/nonce and returns a session token that starts with `tsess_`. Send it as `Authorization: Bearer <token>` to the account and key routes. The account is created on first sign-in with the Free plan. Sessions last 30 days. Costs nothing.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | body | The Sui address that signed (0x + 64 hex). |
| signature | string | yes | body | Base64 Sui signature of the personal message from /v0/auth/nonce. Any scheme works: ed25519, secp256k1, secp256r1, zkLogin, multisig. |
| message | string | no | body | The exact `message` text returned by POST /v0/auth/nonce. Send this, or nonce and issued. |
| nonce | string | no | body | The nonce from POST /v0/auth/nonce (with issued, instead of message). |
| issued | string | no | body | The issued time from POST /v0/auth/nonce (with nonce, instead of message). |

```sh
curl -X POST "https://api.tide.ad/v0/auth/verify?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"address":"0x7d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169677c1be02aaf0b58e","signature":"<base64 signature>","message":"<message from /v0/auth/nonce>"}'
```

### keys.agent

POST /v0/keys/agent

Agents: sign one message with any Sui key, get a Free API key.

One step for agents: call POST /v0/auth/nonce, sign the `message` with any Sui key, then send address, signature and message here. You get the account (created on first use, Free plan) and a new API key in one response. The key is shown once; store it. At most 3 agent keys per address per day, and the Free plan holds 3 keys in total. No email, no payment.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| address | string | yes | body | The Sui address that signed (0x + 64 hex). |
| signature | string | yes | body | Base64 Sui signature of the personal message from /v0/auth/nonce. Any scheme works: ed25519, secp256k1, secp256r1, zkLogin, multisig. |
| message | string | no | body | The exact `message` text returned by POST /v0/auth/nonce. Send this, or nonce and issued. |
| nonce | string | no | body | The nonce from POST /v0/auth/nonce (with issued, instead of message). |
| issued | string | no | body | The issued time from POST /v0/auth/nonce (with nonce, instead of message). |

```sh
curl -X POST "https://api.tide.ad/v0/keys/agent?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"address":"0x7d20dcdb2bca4f508ea9613994683eb4e76e9c4ed371169677c1be02aaf0b58e","signature":"<base64 signature>","message":"<message from /v0/auth/nonce>"}'
```

### keys.list

GET /v0/keys

List your API keys.

Lists the active keys of the signed-in account with name, created and last used times and access rules. The key secret is never shown again after it is created. Needs a session token from POST /v0/auth/verify.

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v0/keys?api-key=YOUR_KEY"
```

### keys.create

POST /v0/keys

Create an API key.

Creates a key for the signed-in account and returns it once in `key`. Optional `allowedOrigins` (for browser use, like `app.example.com` or `*.example.com`) and `allowedIps` (exact address or IPv4 CIDR) restrict where the key works. The plan sets how many keys you can hold. Needs a session token.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| name | string | no | body | A label for you, up to 60 characters. |
| allowedOrigins | array | no | body | Browser origins allowed to use the key. Empty means any. |
| allowedIps | array | no | body | IP addresses or IPv4 CIDR ranges allowed. Empty means any. |

```sh
curl -X POST "https://api.tide.ad/v0/keys?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"name":"backend","allowedOrigins":["app.example.com"]}'
```

### keys.update

PUT /v0/keys/:id

Rename a key or change where it works.

Changes the name, allowed origins or allowed IPs of one of your keys. Fields you leave out stay as they are. Rules apply within 30 seconds.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Key id from GET /v0/keys. |
| name | string | no | body |  |
| allowedOrigins | array | no | body |  |
| allowedIps | array | no | body |  |

```sh
curl -X PUT "https://api.tide.ad/v0/keys/kid_abc123?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"allowedIps":["203.0.113.0/24"]}'
```

### keys.revoke

DELETE /v0/keys/:id

Revoke an API key.

Revokes one of your keys. It stops working within 30 seconds and cannot be restored. Usage already recorded for it stays in your totals.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| id | string | yes | path | Key id from GET /v0/keys. |

```sh
curl -X DELETE "https://api.tide.ad/v0/keys/kid_abc123?api-key=YOUR_KEY"
```

### account.get

GET /v0/account

Your plan, credits used and left this month, and limits.

Returns the plan of the signed-in account, the credits used and left this month (Free stops at zero; paid plans keep working and report `overage`), and every limit of the plan: requests per second per class, streams, webhooks, keys and replay depth. Credits reset on the 1st (UTC).

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v0/account?api-key=YOUR_KEY"
```

### account.usage

GET /v0/account/usage

Usage per day and method.

Returns calls and credits per day and per method for the signed-in account, newest day first. Defaults to the last 30 days; pass `from` and `to` as YYYY-MM-DD (UTC, inclusive) for another range, or `key` to see one key. Recent calls show within about 5 seconds.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| from | string | no | query | First day, YYYY-MM-DD (UTC). Default 30 days ago. |
| to | string | no | query | Last day, YYYY-MM-DD (UTC). Default today. |
| key | string | no | query | Only this key id. |

```sh
curl "https://api.tide.ad/v0/account/usage?from=2026-11-01&to=2026-11-03&api-key=YOUR_KEY"
```

### intel.cases.create

POST /v1/intel/cases (also /v1/omen/cases)

Save an investigation as a case file.

Saves a graph investigation (graph state, notes, annotations and timeline) under your account and returns it with its id. Private unless visibility is link. Up to 1000 cases per account and 2 MB per case. Free; needs a login.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| title | string | no | body | Up to 140 characters. |
| visibility | string (private, link) | no | body | private (owner only, the default) or link (anyone with the link can read it). |
| graph | object | no | body | The visualizer's graph state: nodes with positions, pins, groups, hidden nodes, filters and mode. |
| notes | string | no | body | Markdown notes. |
| annotations | array | no | body | [{ id, target: { kind: node, id } / { kind: edge, key }, text }] |
| entries | array | no | body | Manual timeline entries: [{ id, atMs, text }]. |
| flows | array | no | body | The case's flows for the timeline: [{ key, from, to, fromName, toName, usd, count, coins, firstCheckpoint, lastCheckpoint }]. Times are filled in from the checkpoints. |
| nodeCount | integer | no | body | Visible nodes, shown in the case list. |

```sh
curl -X POST "https://api.tide.ad/v1/intel/cases?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"title":"Drained wallet, Nov 3","notes":"Funds left through two hops."}'
```

### intel.cases.list

GET /v1/intel/cases (also /v1/omen/cases)

List your case files.

Every case on your account, most recently updated first: id, title, visibility, version, node and flow counts and size. Free; needs a login.

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/intel/cases?api-key=YOUR_KEY"
```

### intel.cases.get

GET /v1/intel/cases/:caseID (also /v1/omen/cases/:caseID)

Read one case file.

The whole case: graph state, notes, annotations, manual timeline entries and flows with their first and last times. Owners can always read their cases; anyone can read a case whose visibility is link. mine says whether the caller owns it. Free.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| caseID | string | yes | path | The case id from its link (tide.ad/intel/case/<id>). |

```sh
curl "https://api.tide.ad/v1/intel/cases/Hk3v9QmT2xLp?api-key=YOUR_KEY"
```

### intel.cases.update

PUT /v1/intel/cases/:caseID (also /v1/omen/cases/:caseID)

Save changes to a case file.

Send only what changed: title, visibility, graph, notes, annotations, entries, flows, nodeCount. Pass the version you loaded; when the case changed since, the answer is 409 with the current version. Leave version out to overwrite. Owner only, free.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| caseID | string | yes | path | The case id from its link (tide.ad/intel/case/<id>). |
| title | string | no | body | Up to 140 characters. |
| visibility | string (private, link) | no | body | private (owner only, the default) or link (anyone with the link can read it). |
| graph | object | no | body | The visualizer's graph state: nodes with positions, pins, groups, hidden nodes, filters and mode. |
| notes | string | no | body | Markdown notes. |
| annotations | array | no | body | [{ id, target: { kind: node, id } / { kind: edge, key }, text }] |
| entries | array | no | body | Manual timeline entries: [{ id, atMs, text }]. |
| flows | array | no | body | The case's flows for the timeline: [{ key, from, to, fromName, toName, usd, count, coins, firstCheckpoint, lastCheckpoint }]. Times are filled in from the checkpoints. |
| nodeCount | integer | no | body | Visible nodes, shown in the case list. |
| version | integer | no | body | The version you loaded. |

```sh
curl -X PUT "https://api.tide.ad/v1/intel/cases/Hk3v9QmT2xLp?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"version":1,"notes":"Second hop is a known exchange deposit address."}'
```

### intel.cases.delete

DELETE /v1/intel/cases/:caseID (also /v1/omen/cases/:caseID)

Delete a case file.

Deletes the case for good; its link stops working. Owner only, free.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| caseID | string | yes | path | The case id from its link (tide.ad/intel/case/<id>). |

```sh
curl -X DELETE "https://api.tide.ad/v1/intel/cases/Hk3v9QmT2xLp?api-key=YOUR_KEY"
```

### intel.cases.duplicate

POST /v1/intel/cases/:caseID/duplicate (also /v1/omen/cases/:caseID/duplicate)

Copy a case into your account.

Copies a case you own, or one shared by link, into your account as a new private case and returns it. Free; needs a login.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| caseID | string | yes | path | The case id from its link (tide.ad/intel/case/<id>). |
| title | string | no | body | Up to 140 characters. |

```sh
curl -X POST "https://api.tide.ad/v1/intel/cases/Hk3v9QmT2xLp/duplicate?api-key=YOUR_KEY" -H "content-type: application/json" -d '{}'
```

### account.pins.get

GET /v1/account/pins

Read the pins on your home page.

The cards you pinned on the tide home page (names, coins, perps, pools, collections, packages, transactions), in order. `pins` is null when this account never saved any. Free; needs a login.

Credits: 0. Rate class: light.

No parameters.

```sh
curl "https://api.tide.ad/v1/account/pins?api-key=YOUR_KEY"
```

### account.pins.put

PUT /v1/account/pins

Save the pins on your home page.

Replaces the pins on your home page with the list sent, in order (up to 24). Each pin is { k, id, name, icon, href, sub?, venueLogo?, types? } where k is addr, coin, perp, pool, coll, pkg or tx. Free; needs a login.

Credits: 0. Rate class: light.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| pins | array | yes | body |  |

```sh
curl -X PUT "https://api.tide.ad/v1/account/pins?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"pins":[{"k":"coin","id":"0x2::sui::SUI","name":"SUI","icon":null,"href":"/coin/sui"}]}'
```

## Meta

### meta.index

GET /

What this API is and where to start.

Returns links to the docs, the OpenAPI spec, llms.txt, the MCP endpoint and the status. Costs nothing.

Credits: 0. Rate class: free.

No parameters.

```sh
curl "https://api.tide.ad/?api-key=YOUR_KEY"
```

### meta.status

GET /v0/status

Live status: index head, chain tip, lag and per-method latency.

Use it to check freshness before trusting live answers. `asOf.lagMs` is how far the index is behind the chain tip. `latency` lists p50, p90 and p99 in milliseconds per method over recent calls. Costs nothing.

Credits: 0. Rate class: free.

No parameters.

```sh
curl "https://api.tide.ad/v0/status?api-key=YOUR_KEY"
```

### catalog.json

GET /catalog.json

Every method with params, result schema, example and credits, as JSON.

Returns the full method catalog plus the plans table. Generated from the live method list, so it is always current. Use it to discover methods and their parameters. Costs nothing.

Credits: 0. Rate class: free.

No parameters.

```sh
curl "https://api.tide.ad/catalog.json?api-key=YOUR_KEY"
```

### catalog.openapi

GET /openapi.json

OpenAPI 3.1 description of every REST path and JSON-RPC method.

REST paths are listed as they are called. Each JSON-RPC method is a POST / operation with an x-jsonrpc-method extension and a request body of { jsonrpc, id, method, params }. Use it to generate a typed client. Costs nothing.

Credits: 0. Rate class: free.

No parameters.

```sh
curl "https://api.tide.ad/openapi.json?api-key=YOUR_KEY"
```

### catalog.llms

GET /llms.txt

Short plain-text index for language models: base URLs, auth and one line per method.

A compact map of the API for an agent: what tide is, where to call it, how to authenticate, and one line per method with its credits. Fetch /llms-full.txt for parameters and examples. Costs nothing.

Credits: 0. Rate class: free.

No parameters.

```sh
curl "https://api.tide.ad/llms.txt?api-key=YOUR_KEY"
```

### catalog.llmsFull

GET /llms-full.txt

Plain-text reference: every method with a parameter table and a curl example.

The whole API in one text file for an agent to read: each method with its description, credits, parameter table and a working curl example. Costs nothing.

Credits: 0. Rate class: free.

No parameters.

```sh
curl "https://api.tide.ad/llms-full.txt?api-key=YOUR_KEY"
```

### mcp

POST /mcp

Remote MCP server (streamable HTTP) with tide tools for agents.

Add it to an MCP client as https://api.tide.ad/mcp, with ?api-key=KEY or an Authorization: Bearer KEY header (it also works without a key at the keyless tier). Messages are JSON-RPC 2.0 over POST. Tools: tide_get_transaction, tide_get_wallet, tide_get_coin, tide_search, tide_docs and more. Each tool call costs the credits of the method it runs. The endpoint itself is free.

Credits: 0. Rate class: free.

| Name | Type | Required | Where | Description |
|---|---|---|---|---|
| jsonrpc | string (2.0) | yes | body | JSON-RPC version. |
| id | string|integer | no | body | Request id. Omit for notifications. |
| method | string | yes | body | MCP method: initialize, ping, tools/list, tools/call, notifications/initialized. |
| params | object | no | body | Method parameters. |

```sh
curl -X POST "https://api.tide.ad/mcp?api-key=YOUR_KEY" -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```