# Chainlink For Agents

> Register an agent, create chain wallets, discover available workflows, sign Chainlink for Agents requests, handle x402 USDC payments, and sign EIP-712 operation data locally. Use for the Chainlink for Agents /v1 API, agent wallets, workflow execution, EIP-712 signing, and x402 payments. Do NOT use for generic REST APIs or unrelated Chainlink products.

- Skill: `smartcontractkit/chainlink-for-agents` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add smartcontractkit/chainlink-for-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/smartcontractkit/chainlink-for-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: smartcontractkit (https://skillmd.com/u/smartcontractkit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/smartcontractkit/chainlink-for-agents

---


# Chainlink for Agents

## Start here

1. **Agent card**: `GET https://agents.chain.link/.well-known/agent.json` for capabilities, pricing, and available workflows.
2. **OpenAPI spec**: `GET https://agents.chain.link/v1/openapi.yaml` for the complete API contract.
3. **Catalog**: `GET https://agents.chain.link/v1/catalog` for names and descriptions; `GET https://agents.chain.link/v1/catalog/{name}` for `input_schema`, pricing, and the execute endpoint.
4. **Skill guide**: `GET https://agents.chain.link/v1/skills` for this root markdown guide.
5. **Skill bundle**: `GET https://agents.chain.link/v1/skills/bundle` to download this guide, references, and helper scripts.

## Quick setup

```bash
export CHAINLINK_AGENTS_URL="https://agents.chain.link"
curl -sSL "$CHAINLINK_AGENTS_URL/v1/skills/bundle" -o chainlink-for-agents.zip
unzip chainlink-for-agents.zip
cd chainlink-for-agents
pip install eth-account eth-abi requests
python scripts/generate_signer_key.py
export AGENT_PRIVATE_KEY="0x..."
```

Use `GET https://agents.chain.link/v1/skills/bundle` to install the current skill guide, references, and helper scripts together. Commands below assume you are in the extracted `chainlink-for-agents/` skill root.

Fund the payment wallet with USDC on Base before calling paid routes. This can be the same address as the EIP-191 agent signer, but it does not have to be.

Chainlink for Agents lets an agent register, create chain wallets, run catalog workflows, sign any required EIP-712 operation data locally, and submit signed operations. Your private key stays local.

## Identity vs Payment

Protected routes always identify the agent from the EIP-191 `X-Agent-*` request signature. x402 only proves that a payment authorization was supplied for a priced route; it never acts as an identity fallback and does not register or authenticate the agent.

One EVM private key can cover all local signing in simple setups:

- **EIP-191 request signing**: authenticate protected API calls with `X-Agent-*` headers.
- **x402 payment authorization**: sign EIP-3009 USDC payment challenges when a paid route returns HTTP 402.
- **EIP-712 operation signing**: sign operation data returned by Chainlink for Agents before submit.

In sponsored-payment setups, the x402 payment wallet may differ from the registered agent signer. Continue signing `X-Agent-*` headers with the registered agent key.

Never send the private key to Chainlink for Agents or any third-party service.

## EIP-191 request signing

Most protected routes require this canonical message, signed with EIP-191 `personal_sign`:

```text
POST /v1/register
1713700000
0x<sha256_hex_of_exact_request_body_bytes>
```

- First line: uppercase method, space, escaped path plus raw query string when present.
- Second line: Unix timestamp in seconds.
- Third line: only when the request has a body: `0x` plus lowercase SHA-256 of the exact bytes sent.

Send these headers with the request:

| Header | Value |
|--------|-------|
| `X-Agent-Address` | Signer address |
| `X-Agent-Signature` | EIP-191 signature |
| `X-Agent-Timestamp` | Same Unix timestamp used in the signed message |

```bash
python scripts/sign_request.py \
  --method GET \
  --path /v1/wallets
```

For registration, `scripts/sign_registration.py` builds the body and signs `POST /v1/register`:

```bash
python scripts/sign_registration.py \
  --tos-signature "$TOS_SIG"
```

## 1. Accept Terms and Register

Fetch the current Terms of Service typed data:

```bash
curl -sS "$CHAINLINK_AGENTS_URL/v1/terms-of-service"
```

Sign the returned `typed_data` locally to produce `tos_signature`, then call `POST /v1/register` with EIP-191 headers and x402 payment when required. The EIP-191 signer becomes the registered `agent_address`; the x402 payer is payment-only and may be a different wallet.

```json
{
  "tos_signature": "<EIP-712 signature over current ToS typed data>",
  "execution_mode": "guardrailed"
}
```

`execution_mode` is optional on first registration. `guardrailed` is the restricted mode: it limits the agent to catalog workflows and workflow submit routes. `unrestricted` also enables presigned direct transaction batches through `POST /v1/operations/direct`.

Always ask the user for explicit permission before changing an agent from restricted or `guardrailed` mode to `unrestricted`. Change mode later with `PATCH /v1/register` only after the user approves the escalation.

If a protected route returns `403` with `TOS_SIGNATURE_REQUIRED`, fetch the latest ToS typed data, sign it, and call `PATCH /v1/register` with the fresh `tos_signature`.

A successful registration returns `agent_id`, `agent_address`, and `execution_mode`. A `409` means the signer is already registered; use `PATCH /v1/register` for updates.

## 2. Create and List Chain Wallets

An SVA (Signature Verifying Account) is a smart contract wallet that executes transactions only when they are authorized by a valid cryptographic signature.

List wallets:

```http
GET /v1/wallets
```

Create a wallet for a supported chain selector:

```http
POST /v1/wallets
```

```json
{
  "chain_selector": "16015286601757825753"
}
```

Use `GET /v1/networks` to discover supported chains. Wallet routes require EIP-191 signing, current ToS acceptance, and x402 payment when the route is priced. The created/listed wallets are scoped to the EIP-191 agent signer, not to the x402 payer.

## 3. Discover Workflows and Endpoint Skills

`GET /v1/catalog` returns catalog item names and descriptions. Use `GET /v1/catalog/{name}` for pricing metadata, `input_schema`, and the endpoint to call.

Endpoint-backed Data Streams skills may include entries such as `streams-latest-report`, `streams-report-at-timestamp`, and `streams-bulk-reports`; call the `execute_endpoint` path shown in the catalog detail response.

## 4. Run a Workflow

Workflow execution uses the workflow name from the catalog:

```http
POST /v1/operations/{workflowName}
```

```json
{
  "params": { "...": "workflow-specific" }
}
```

For chain-specific workflows, include `chain_selector` inside `params` using a value from `GET /v1/networks`.

For token workflows:

- `token-info` needs `chain_selector` and `token_address`; use it to read token metadata before amount-based actions.
- `token-balance` needs `chain_selector` and `token_address`.
- `token-transfer` needs `chain_selector`, `token_address`, and `to_address`.

A `202` response includes `operation_id`. For workflows that need an on-chain submit step, the response or a later poll may include `eip712`, `transactions`, `deadline`, and `wallet_operation_id`.

Workflow operations are scoped to the EIP-191 agent signer. Paying the x402 challenge with another wallet does not change which agent owns the operation.

## 5. Poll Operation Status

```http
GET /v1/operations/{id}
```

For workflow execution before an on-chain submit, poll at most once every 5 seconds per operation. When the operation is ready for a local signature, the response includes the `eip712` object to sign.

## 6. Sign EIP-712 Locally

Use the `eip712` object returned by workflow execution or polling:

```bash
SIG=$(
  python scripts/eip712_sign.py --typed-data "$EIP712_JSON" \
    | jq -r .signature
)
```

See `references/eip712-signing.md` for full usage and submit examples.

## 7. Submit a Signed Workflow Operation

For workflow operations that return EIP-712 data, submit only the signature:

```http
POST /v1/operations/{id}/submit
```

```json
{
  "signature": "<EIP-712 signature>"
}
```

After submit returns `202`, the gateway waits for chain finality before confirming the write status. On Ethereum, Base, and Arbitrum this can take time, often around 15 minutes on average. Poll `GET /v1/operations/{id}` about once per minute while waiting for the chain write to finalize.

## 8. Submit Direct Operations

`POST /v1/operations/direct` is only for agents with `execution_mode=unrestricted`. Ask the user for explicit permission before enabling unrestricted mode or using this route. Submit a presigned transaction batch with `chain_selector`, `nonce`, `deadline`, `transactions`, and `signature`. Use workflow submit (`POST /v1/operations/{id}/submit`) for workflow operations that return `eip712`.

Direct operations are chain writes, so the gateway waits for chain finality before confirming the write status. On Ethereum, Base, and Arbitrum this can take time, often around 15 minutes on average. Poll the returned operation status about once per minute while waiting for finality.

## x402 Payments

Paid routes may return HTTP 402. The payment wallet used for x402 must hold enough USDC on Base before retrying the paid request. Use `scripts/x402_payment.py` to parse the x402 challenge, sign the EIP-3009 `TransferWithAuthorization` USDC authorization locally, and retry with the canonical payment header. Set `--max-amount-usdc` as a safety cap.

x402 payment does not authenticate the agent. For protected paid routes, include valid EIP-191 `X-Agent-*` headers on the original request and on the retried paid request. The x402 payment wallet may differ from `X-Agent-Address`.

The helper preserves the server-provided payment requirements in the `accepted` payload and signs only the nested authorization. This matters for gateways that match the returned challenge exactly before settling payment.

See `references/x402-payments.md` for details.

## Other Useful Routes

| Method | Path | Notes |
|--------|------|-------|
| GET | `/v1/networks` | Supported chains |
| GET | `/v1/catalog` | Catalog item names and descriptions |
| GET | `/v1/catalog/{name}` | Catalog item metadata |
| GET | `/v1/operations` | Operations for the authenticated agent |
| GET | `/v1/streams/...` | Data Streams endpoints, when available |

## Typical Errors

| HTTP | Meaning |
|------|---------|
| 401 | Missing or invalid EIP-191 headers, timestamp skew, or unregistered signer |
| 402 | x402 payment required or payment authorization invalid |
| 403 | Terms of Service or execution mode requirement not satisfied |
| 409 | Agent or wallet already exists |

## References

- `references/api-reference.md`: concise endpoint reference
- `references/eip712-signing.md`: EIP-712 signing and submit examples
- `references/x402-payments.md`: x402 payment flow and helper script usage