Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions typescript/.changeset/agent-data-apis-provider.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@coinbase/agentkit": patch
---

Added the Agent Data APIs action provider with x402-paid pre-trade and pre-payment safety checks: `check_token_risk` (honeypot and buy/sell tax simulation, owner powers), `check_payment_counterparty` (sanctioned crypto addresses, x402 seller reputation) and `screen_sanctions` (OFAC, UN, EU, UK name screening).
44 changes: 44 additions & 0 deletions typescript/agentkit/src/action-providers/agentDataApis/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Agent Data APIs Action Provider

This directory contains the **AgentDataApisActionProvider**, which gives agents pre-trade and pre-payment safety checks from [Agent Data APIs](https://agent-payment-guard.agent-data-apis.workers.dev/llms.txt). Each check is paid per call with [x402](https://x402.org) (USDC on Base) from the agent's own wallet. No API key or account is needed.

## Directory Structure

```
agentDataApis/
├── agentDataApisActionProvider.ts # Main provider
├── agentDataApisActionProvider.test.ts # Tests
├── schemas.ts # Action schemas and config type
├── index.ts # Exports
└── README.md # This file
```

## Actions

| Action | Use it | Returns | Price |
|---|---|---|---|
| `check_token_risk` | Before buying, swapping into or accepting a token | `avoid` / `caution` / `ok`; buy/sell tax and round-trip cost from a simulated buy then sell on the token's deepest ETH/WETH pool (Uniswap V2, V3 and V4 plus Aerodrome on Base; Uniswap V2, V3 and V4 on Ethereum), catching honeypots including V4 hooks that confiscate sells; owner powers (mint, pause, blacklist, fee changes, trading switch); proxy; liquidity; sanctioned owner; signed receipt | ~$0.01 |
| `check_payment_counterparty` | Before sending funds to an address (including x402 payTo addresses) | `block` / `review` / `clear`, sanctioned crypto address match (OFAC, UK, EU), x402 seller reputation, live on-chain facts, optional name screening, signed receipt | ~$0.005 |
| `screen_sanctions` | KYC/KYB-style name checks | Scored candidate matches against OFAC (SDN + Consolidated), UN, EU and UK lists | ~$0.01 |

## Configuration

```typescript
import { agentDataApisActionProvider } from "@coinbase/agentkit";

const provider = agentDataApisActionProvider({
// Maximum USDC the agent may pay for a single check.
// Default: 0.05 (or AGENT_DATA_APIS_MAX_PAYMENT_USDC env var)
maxPaymentUsdc: 0.05,
});
```

Before paying, the provider reads the price from the HTTP 402 challenge and refuses to pay if it is above `maxPaymentUsdc` or if no USDC-on-Base option is offered.

## Network Support

The wallet must be on **Base mainnet** (`base-mainnet`), since checks are paid in USDC on Base. The checks themselves cover Base, Ethereum, Arbitrum, Optimism and Polygon addresses and tokens.

## Notes

Results are automated screening signals and simulations at the current block, not financial or legal advice. Contract rules can change after a check (for example through upgrades or owner actions).
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
import { agentDataApisActionProvider } from "./agentDataApisActionProvider";
import { EvmWalletProvider } from "../../wallet-providers";
import { wrapFetchWithPayment } from "@x402/fetch";

jest.mock("@x402/fetch", () => ({
x402Client: jest.fn().mockImplementation(() => ({})),
wrapFetchWithPayment: jest.fn(),
}));
jest.mock("@x402/evm/exact/client", () => ({ registerExactEvmScheme: jest.fn() }));

const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const TOKEN = "0x95c7082fb200C77Cf0fF7849CC8cC8177e6f91BD";

/**
* Builds a mock 402 response carrying an x402 v2 PAYMENT-REQUIRED header.
*
* @param amountAtomic - Price in USDC atomic units (6 decimals)
* @returns A mock Response-like object
*/
function paymentRequired(amountAtomic: string) {
const challenge = {
x402Version: 2,
accepts: [{ scheme: "exact", network: "eip155:8453", asset: BASE_USDC, amount: amountAtomic }],
};
return {
ok: false,
status: 402,
headers: {
get: (h: string) => (h === "payment-required" ? btoa(JSON.stringify(challenge)) : null),
},
text: jest.fn().mockResolvedValue("{}"),
};
}

describe("AgentDataApisActionProvider", () => {
const fetchMock = jest.fn();
global.fetch = fetchMock;
const walletProvider = {
toSigner: jest.fn().mockReturnValue({ address: "0x0000000000000000000000000000000000000001" }),
readContract: jest.fn(),
} as unknown as EvmWalletProvider;

beforeEach(() => {
jest.clearAllMocks();
});

it("supports only Base mainnet", () => {
const provider = agentDataApisActionProvider();
expect(provider.supportsNetwork({ protocolFamily: "evm", networkId: "base-mainnet" })).toBe(
true,
);
expect(provider.supportsNetwork({ protocolFamily: "evm", networkId: "base-sepolia" })).toBe(
false,
);
expect(provider.supportsNetwork({ protocolFamily: "svm", networkId: "solana-mainnet" })).toBe(
false,
);
});

it("pays and returns the token check when the price is within the limit", async () => {
fetchMock.mockResolvedValueOnce(paymentRequired("10000")); // $0.01
const paidFetch = jest.fn().mockResolvedValue({
ok: true,
status: 200,
json: jest.fn().mockResolvedValue({ verdict: "caution", simulation: { sell_tax_pct: 9.95 } }),
});
(wrapFetchWithPayment as jest.Mock).mockReturnValue(paidFetch);

const result = JSON.parse(
await agentDataApisActionProvider().checkTokenRisk(walletProvider, {
tokenAddress: TOKEN,
chain: "ethereum",
}),
);

expect(result.verdict).toBe("caution");
expect(result.paid_usdc).toBe(0.01);
expect(paidFetch).toHaveBeenCalledWith(
expect.stringContaining(`/v1/token?address=${TOKEN}&chain=ethereum`),
);
});

it("refuses to pay above the configured limit", async () => {
fetchMock.mockResolvedValueOnce(paymentRequired("1000000")); // $1.00
const result = await agentDataApisActionProvider({ maxPaymentUsdc: 0.05 }).checkTokenRisk(
walletProvider,
{ tokenAddress: TOKEN, chain: "base" },
);
expect(result).toContain("above the configured limit");
expect(wrapFetchWithPayment).not.toHaveBeenCalled();
});

it("refuses to pay when no USDC-on-Base option is offered", async () => {
fetchMock.mockResolvedValueOnce({
ok: false,
status: 402,
headers: { get: () => null },
text: jest.fn().mockResolvedValue(""),
});
const result = await agentDataApisActionProvider().checkPaymentCounterparty(walletProvider, {
address: "0x0000000000000000000000000000000000000002",
chain: "base",
});
expect(result).toContain("not paying");
expect(wrapFetchWithPayment).not.toHaveBeenCalled();
});

it("passes the counterparty name and entity type through as query parameters", async () => {
fetchMock.mockResolvedValue({
ok: true,
status: 200,
json: jest.fn().mockResolvedValue({ verdict: "review" }),
});
const provider = agentDataApisActionProvider();

await provider.checkPaymentCounterparty(walletProvider, {
address: "0x0000000000000000000000000000000000000002",
chain: "base",
counterpartyName: "Viktor Bout",
});
expect(fetchMock).toHaveBeenLastCalledWith(expect.stringContaining("name=Viktor+Bout"));

await provider.screenSanctions(walletProvider, { name: "Sovcomflot", entityType: "entity" });
expect(fetchMock).toHaveBeenLastCalledWith(
expect.stringContaining("/v1/screen?name=Sovcomflot&type=entity"),
);
});

it("returns an error string on network failure", async () => {
fetchMock.mockRejectedValueOnce(new Error("network down"));
const result = await agentDataApisActionProvider().screenSanctions(walletProvider, {
name: "Acme",
});
expect(result).toContain("network down");
});
});
Loading
Loading