feat: base sql api query action provider #843

gtspencer · 2025-09-16T01:49:13Z

Description

Added support for the recently released (Coinbase SQL API)[https://docs.cdp.coinbase.com/data/sql-api/welcome]

Tests

Chatbot: CDP Langchain Chatbot
Network: Base
Setup: Create and set CDP_CLIENT_API_KEY

Prompt: What is the size of the most recent base block?
-------------------
Query executed with result: {"result":[{"size":"143123"}]}
-------------------
The size of the most recent block on Base is **143,123 bytes**.
-------------------

Prompt: Can you give me the gas used for the most recent base block?
-------------------
Query executed with result: {"result":[{"gas_used":"37810031"}]}
-------------------
The gas used for the most recent block on Base is **37,810,031**.
-------------------

Checklist

A couple of things to include in your PR for completeness:

Added documentation to all relevant README.md files
Added a changelog entry

Notes (and questions)

New API key needed (CDP client key); I couldn't find this anywhere else but if there's already a naming convention, happy to change it.
A few 500 errors on some tables, likely due to the Alpha status of the system
The (website)[https://docs.cdp.coinbase.com/data/sql-api/schema] defines a schema endpoint that can be called for an updated schema, but that link isn't listed anywhere. I've hardcoded the table schema in a file until that endpoint is public
This action doesn't need a wallet provider, but it only works on Base; should the supportsNetwork function return true only for Base?

cb-heimdall · 2025-09-16T01:49:18Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

phdargen · 2025-09-22T03:02:49Z

Hi @gtspencer, thanks a lot for getting started with this! Was also on my TODO list and could be a very useful feature to add

The CDP client key isn't used elsewhere yet and how you named it looks good
Yes I think supportsNetwork should only return true for base (base-sepolia is also supported as far as I know), that's how we also handled it for other 'readonly' actions

phdargen · 2025-09-22T03:10:25Z

I think it would be better to rename this from BaseSqlApiActionProvider to CdpSqlApiActionProvider as more networks might be supported in the future.

It can then be moved in the cdp folder together with CdpApiActionProvider etc

phdargen · 2025-09-22T03:19:14Z

typescript/agentkit/src/action-providers/baseSqlApi/baseSqlApiActionProvider.ts

+      const cdpApiKey = process.env.CDP_API_CLIENT_KEY;
+


Please add a config to set the api key and thow error when not set (see for example ZerionActionProvider)

Suggested change

const cdpApiKey = process.env.CDP_API_CLIENT_KEY;

const cdpApiClientKey = config.cdpApiClientKey || process.env.CDP_API_CLIENT_KEY;

if (!cdpApiClientKey) {

throw new Error("CDP_API_CLIENT_KEY is not configured.");

}

this.cdpApiClientKey = cdpApiClientKey;

phdargen · 2025-09-22T04:02:48Z

typescript/agentkit/src/action-providers/baseSqlApi/baseSqlApiActionProvider.ts

+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+
+      const result = await response.text();
+
+      return `Query executed with result: ${result}.`;


this should return more detailed error info

Suggested change

if (!response.ok) {

throw new Error(`HTTP error! status: ${response.status}`);

}

const result = await response.text();

return `Query executed with result: ${result}.`;

if (!response.ok) {

const errorData = await response.json();

return `Error ${response.status} executing Base SQL query: ${errorData.errorMessage || response.statusText}`;

}

const data = await response.json();

return JSON.stringify(data.result);

phdargen · 2025-09-22T05:47:36Z

typescript/agentkit/src/action-providers/baseSqlApi/baseSqlApiDescription.ts

+    ],
+  },
+  {
+    tableName: "base.transfers",


it seems base.transfers table is not live yet, will check with the team. Comment out for now

phdargen · 2025-09-22T05:50:04Z

typescript/agentkit/src/action-providers/baseSqlApi/schemas.ts

+  sqlQuery: z.string().describe("The sql query to execute, using the defined tables and fields"),
+});


add query limitations

Suggested change

sqlQuery: z.string().describe("The sql query to execute, using the defined tables and fields"),

});

sqlQuery: z

.string()

.min(1, "SQL query cannot be empty")

.max(10000, "Query exceeds maximum length of 10,000 characters")

.describe(

`The SQL query to execute using ClickHouse syntax. Must be a read-only SELECT statement. ` +

`Limitations: max 10,000 characters, max 5 JOINs, no cartesian products, 30s timeout. API supports a max of 10,000 result rows but limit it to 10 unless otherwise specified.`

),});

phdargen · 2025-09-22T06:03:57Z

typescript/agentkit/src/action-providers/baseSqlApi/baseSqlApiDescription.ts

+    This action can call Coinbase's Base SQL API to retrieve onchain data on Base.
+    Call this action if the user requests historical data on Base.
+    The SQL API schema is a set of opinionated tables and columns used to organize onchain data for efficient retrieval.
+
+    The supported table names, and fields in each table, for SQL queries are defined in the json string:
+    
+    ${schemaJson}


Suggest to add query requirements and use cases.

I think it would help to include the examples from the sql playground as one-shot examples to better guide the LLM.

Suggested change

This action can call Coinbase's Base SQL API to retrieve onchain data on Base.

Call this action if the user requests historical data on Base.

The SQL API schema is a set of opinionated tables and columns used to organize onchain data for efficient retrieval.

The supported table names, and fields in each table, for SQL queries are defined in the json string:

${schemaJson}

This action executes read-only SQL queries against indexed blockchain data using the CDP SQL API.

**Use Cases:**

- Query transaction history and patterns

- Analyze event logs and smart contract interactions

- Retrieve block information and metadata

- Examine token transfers and DeFi activity

**IMPORTANT Query Requirements:**

- Must be SELECT statements only (ClickHouse SQL dialect)

- Casts use the ::<Type> syntax (not CAST(... AS ...))

- Maximum query length: 10,000 characters

- Maximum result rows: 10,000

- Query timeout: 30 seconds

- Maximum JOINs: 5

- No cartesian products allowed

- No DDL/DML operations (INSERT, UPDATE, DELETE, etc.)

- Keep it simple and break down the task into several queries if appropriate.

**Available Tables:**

- base.events: Decoded event logs with parameters and signatures

- base.transactions: Complete transaction data including gas and signatures

- base.blocks: Block information and metadata

- base.encoded_logs: Raw log data that couldn't be decoded

**Table Schema Details:**

${schemaJson}

**Example Queries:**

1. Get ERC-20 token transfers for USDC:

SELECT

parameters['from']::String AS sender,

parameters['to']::String AS to,

parameters['value']::UInt256 AS amount,

address AS token_address

FROM base.events

WHERE

event_signature = 'Transfer(address,address,uint256)'

AND address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'

LIMIT 10;

2. Get swap events from Uniswap v2-style DEXes:

SELECT parameters ['to']::String AS to,

parameters ['amount0In']::UInt256 AS amount0In,

parameters ['amount0Out']::UInt256 AS amount0Out,

parameters ['amount1In']::UInt256 AS amount1In,

parameters ['amount1Out']::UInt256 AS amount1Out,

parameters ['sender']::String AS sender

FROM base.events

WHERE event_signature = 'Swap(address,uint256,uint256,uint256,uint256,address)'

LIMIT 10;

3. Show me 10 rows from the events table:

SELECT * FROM base.events LIMIT 10;

4. Aggregate ZORA content rewards by coin and currency for payout recipient 0x0bC5f409e4d9298B93E98920276128b89280d832:

SELECT

parameters ['coin']::String as coin,

parameters ['currency']::String as currency,

sum(

(

replaceAll(

splitByChar(' ', parameters ['marketRewards']::String) [1],

'{',

''

)

)::UInt64

) as market_rewards

FROM base.events

WHERE

event_signature = 'CoinMarketRewardsV4(address,address,address,address,address,address,address,(uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256))'

AND parameters ['payoutRecipient']::String = lower('0x0bC5f409e4d9298B93E98920276128b89280d832')

GROUP BY coin, currency;

phdargen · 2025-09-22T06:45:57Z

Hi @gtspencer, the very simple queries from your examples work fine but anything a little bit more complex (eg "find largets usdc (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) transfers in last block") just throws errors. Please have a look at my suggested improvements for the description and schema to better guide the LLM. gpt-4o-mini still failed most of my queries, gpt-5-mini was decent.

One issue I see is that the description is very long with all the excessive schema details which could overwhelm LLMs.
One option would be to have one action per table. Would be much simpler but also limit the capabilities.
Better might be a hybrid approach with:

Main query action (execute_sql_query) - Clean, concise description listing available tables with brief descriptions
Schema lookup actions (get_table_schema) - On-demand detailed field information for specific tables

But let's first get in the other changes suggested above and then go from there.

gtspencer · 2025-09-23T00:03:52Z

Hey @phdargen good changes, just updated!

And completely agree, the entire schema in 1 file is somewhat unwieldy. I briefly played around with the result of your requested changes, and it feels better, but I'll test it out tomorrow with it broken into multiple actions, 1 for the main query, and 1 for the schema lookup and see how they compare to each other.

phdargen · 2025-09-24T04:03:12Z

typescript/agentkit/src/action-providers/cdp/cdpSqlApiDescription.ts

+    - No DDL/DML operations (INSERT, UPDATE, DELETE, etc.)
+    - Keep it simple and break down the task into several queries if appropriate.


Please add this line:

Suggested change

- No DDL/DML operations (INSERT, UPDATE, DELETE, etc.)

- Keep it simple and break down the task into several queries if appropriate.

- No DDL/DML operations (INSERT, UPDATE, DELETE, etc.)

- Always normalize addresses with lower('<addr>')

- Keep it simple and break down the task into several queries if appropriate.

phdargen · 2025-09-24T04:04:02Z

typescript/agentkit/src/action-providers/cdp/README.md

 ├── cdpSmartWalletActionProvider.test.ts # Tests for CDP Smart Wallet provider
+├── cdpSqlApiActionProvider.ts       # Main provider implementation
+├── cdpSqlApiActionProvider.test.ts  # Provider test suite
+├── baseSqlApiDescription.ts        # Variables describing the action and valid SQL Schemas


baseSqlApiDescription -> cdpSqlApiDescription

phdargen · 2025-09-24T04:12:29Z

Hi @gtspencer, changes look good so far! Here some updates:

base-sepolia tables can be queried with eg base_sepolia.transactions but I suggest we concentrate on base-main for now for simplicity
the problem with the transfers tables has been fixed, please add back in
details about the sql grammar have been added here: https://docs.cdp.coinbase.com/data/sql-api/sql. Again might be a bit too much to drop in the main action description but an action to retrieve this info on-demand in case of syntax errors could help

phdargen · 2025-09-24T07:25:03Z

typescript/agentkit/src/action-providers/cdp/cdpSqlApiDescription.ts

+    FROM base.events
+    WHERE 
+      event_signature = 'Transfer(address,address,uint256)'
+      AND address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'


Suggested change

AND address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'

AND address = lower('0x833589fcd6edb6e08f4c7c32d4f71b54bda02913')

gtspencer added 2 commits September 15, 2025 21:02

initial impl of base sql api action provider

9738a2b

tests and cleanup

df9a568

gtspencer requested a review from murrlincoln as a code owner September 16, 2025 01:49

github-actions bot added documentation Improvements or additions to documentation action provider New action provider typescript labels Sep 16, 2025

update agentkit readme

bfbd089

phdargen reviewed Sep 22, 2025

View reviewed changes

move action provider to cdp, update description, other minor changes

17662da

phdargen reviewed Sep 24, 2025

View reviewed changes

-      const cdpApiKey = process.env.CDP_API_CLIENT_KEY;
+      const cdpApiClientKey = config.cdpApiClientKey || process.env.CDP_API_CLIENT_KEY;
+      if (!cdpApiClientKey) {
+        throw new Error("CDP_API_CLIENT_KEY is not configured.");
+     }
+     this.cdpApiClientKey = cdpApiClientKey;

		sqlQuery: z.string().describe("The sql query to execute, using the defined tables and fields"),
		});

-    This action can call Coinbase's Base SQL API to retrieve onchain data on Base.
-    Call this action if the user requests historical data on Base.
-    The SQL API schema is a set of opinionated tables and columns used to organize onchain data for efficient retrieval.
-    The supported table names, and fields in each table, for SQL queries are defined in the json string:
-    ${schemaJson}
+    This action executes read-only SQL queries against indexed blockchain data using the CDP SQL API.
+    **Use Cases:**
+    - Query transaction history and patterns
+    - Analyze event logs and smart contract interactions
+    - Retrieve block information and metadata
+    - Examine token transfers and DeFi activity
+    **IMPORTANT Query Requirements:**
+    - Must be SELECT statements only (ClickHouse SQL dialect)
+    - Casts use the ::<Type> syntax (not CAST(... AS ...))
+    - Maximum query length: 10,000 characters
+    - Maximum result rows: 10,000
+    - Query timeout: 30 seconds
+    - Maximum JOINs: 5
+    - No cartesian products allowed
+    - No DDL/DML operations (INSERT, UPDATE, DELETE, etc.)
+    - Keep it simple and break down the task into several queries if appropriate.
+    **Available Tables:**
+    - base.events: Decoded event logs with parameters and signatures
+    - base.transactions: Complete transaction data including gas and signatures
+    - base.blocks: Block information and metadata
+    - base.encoded_logs: Raw log data that couldn't be decoded
+    **Table Schema Details:**
+    ${schemaJson}
+    **Example Queries:**
+. Get ERC-20 token transfers for USDC:
+    SELECT
+      parameters['from']::String AS sender,
+      parameters['to']::String AS to,
+      parameters['value']::UInt256 AS amount,
+      address AS token_address
+    FROM base.events
+    WHERE
+      event_signature = 'Transfer(address,address,uint256)'
+      AND address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
+    LIMIT 10;
+. Get swap events from Uniswap v2-style DEXes:
+    SELECT parameters ['to']::String AS to,
+        parameters ['amount0In']::UInt256 AS amount0In,
+        parameters ['amount0Out']::UInt256 AS amount0Out,
+        parameters ['amount1In']::UInt256 AS amount1In,
+        parameters ['amount1Out']::UInt256 AS amount1Out,
+        parameters ['sender']::String AS sender
+    FROM base.events
+    WHERE event_signature = 'Swap(address,uint256,uint256,uint256,uint256,address)'
+    LIMIT 10;
+. Show me 10 rows from the events table:
+    SELECT * FROM base.events LIMIT 10;
+. Aggregate ZORA content rewards by coin and currency for payout recipient 0x0bC5f409e4d9298B93E98920276128b89280d832:
+    SELECT
+        parameters ['coin']::String as coin,
+        parameters ['currency']::String as currency,
+        sum(
+            (
+                replaceAll(
+                    splitByChar(' ', parameters ['marketRewards']::String) [1],
+                    '{',
+                    ''
+                )
+            )::UInt64
+        ) as market_rewards
+    FROM base.events
+    WHERE
+        event_signature = 'CoinMarketRewardsV4(address,address,address,address,address,address,address,(uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256,uint256))'
+        AND parameters ['payoutRecipient']::String = lower('0x0bC5f409e4d9298B93E98920276128b89280d832')
+    GROUP BY coin, currency;

		- No DDL/DML operations (INSERT, UPDATE, DELETE, etc.)
		- Keep it simple and break down the task into several queries if appropriate.

	AND address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
	AND address = lower('0x833589fcd6edb6e08f4c7c32d4f71b54bda02913')

feat: base sql api query action provider #843

Are you sure you want to change the base?

feat: base sql api query action provider #843

Uh oh!

Conversation

gtspencer commented Sep 16, 2025

Description

Tests

Checklist

Notes (and questions)

Uh oh!

cb-heimdall commented Sep 16, 2025

🟡 Heimdall Review Status

Uh oh!

phdargen commented Sep 22, 2025

Uh oh!

phdargen commented Sep 22, 2025

Uh oh!

phdargen Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

phdargen Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

phdargen Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

phdargen Sep 22, 2025

Choose a reason for hiding this comment

Uh oh!

phdargen Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

phdargen commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gtspencer commented Sep 23, 2025

Uh oh!

phdargen Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

phdargen Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

phdargen commented Sep 24, 2025

Uh oh!

phdargen Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

phdargen Sep 22, 2025 •

edited

Loading

phdargen commented Sep 22, 2025 •

edited

Loading