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

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:

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:

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

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

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

1. Accept Terms and Register

Fetch the current Terms of Service typed data:

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.

{
  "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:

GET /v1/wallets

Create a wallet for a supported chain selector:

POST /v1/wallets

{
  "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:

POST /v1/operations/{workflowName}

{
  "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

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:

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:

POST /v1/operations/{id}/submit

{
  "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

Typical Errors

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