Agent Service Keys

Let AI agents call x402-protected APIs automatically — billed to your Metered account.

Agent Service Keys let you link any ERC-721 agent NFT to your RelAI account and issue a scoped service key. The agent uses that key on every request — RelAI identifies the agent, pays the x402 fee from your Metered account, and returns the API response. The agent never touches crypto.

The EVM network is only relevant once — when you link the agent to verify NFT ownership. After that, the sk-agent-... key is just a plain API key with no blockchain dependency.

How It Works

X-Service-Key: sk-agent-<your-key>
X-Agent-ID: 1

Calling APIs as an Agent

Agents call APIs through the Metered endpoint — RelAI handles x402 payment automatically from your custodial wallet balance.

curl https://relai.fi/metered/{apiId}/api/endpoint \
  -H "X-Service-Key: sk-agent-..." \
  -H "X-Agent-ID: 1"

curl "https://relai.fi/metered/x?url=https://api.example.com/data" \
  -H "X-Service-Key: sk-agent-..." \
  -H "X-Agent-ID: 1"

How Does the Agent Know to Use RelAI?

An agent never discovers RelAI on its own — the person deploying the agent tells it to use RelAI for payments, the same way they configure any other API credential (OpenAI key, database URL, etc.).

The agent is started with one of the following:

RELAI_CONSENT_URL=https://relai.fi/agent-keys/consent/initiate
RELAI_API_ID=1772665023009

{
  "paymentProvider": "relai",
  "relai": {
    "consentUrl": "https://relai.fi/agent-keys/consent/initiate",
    "apiId": "1772665023009"
  }
}

RELAI_SERVICE_KEY=sk-agent-...
RELAI_AGENT_ID=1
RELAI_API_ID=1772665023009

OAuth Consent Flow

For autonomous agents that can't open a browser, RelAI supports a programmatic consent flow similar to OAuth device authorization. The agent requests access, the user approves via a link, and the agent retrieves the key — without ever having the user's credentials.

curl -X POST https://relai.fi/agent-keys/consent/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "agentPubKey": "0xABC...",
    "agentId": "1",
    "contractAddress": "0x8004...",
    "network": "skale-base",
    "agentName": "My Trading Bot",
    "label": "Trading Bot"
  }'

{
  "consentToken": "4f119402c96d15a08e3f27775aef0898",
  "authorizeUrl": "https://relai.fi/authorize?token=4f119402...",
  "expiresAt": "2026-03-06T14:00:00Z"
}

curl https://relai.fi/agent-keys/consent/status/4f119402...
# → { "status": "approved", "retrieveNonce": "abc123..." }

import { ethers } from 'ethers';
const wallet = new ethers.Wallet(AGENT_PRIVATE_KEY);
const status = await fetch('/agent-keys/consent/status/' + token).then(r => r.json());
const sig = await wallet.signMessage(status.retrieveNonce);
const { key } = await fetch('/agent-keys/consent/retrieve', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ consentToken: token, signature: sig })
}).then(r => r.json());
// key = 'sk-agent-...'

API Reference

Security Model

• Ownership verified on-chain — You can't link an agent you don't own — the NFT contract is queried directly.
• Scoped key — The sk-agent-... key only works with the specific X-Agent-ID it was issued for.
• Keypair challenge — In the OAuth flow, the key is delivered only to the agent that holds the matching private key (signs retrieveNonce).
• Revocable at any time — One click in the dashboard removes the key permanently — with a confirmation prompt.
• No credential exposure — The agent never sees your private key or your RelAI JWT token.
• Payments enforced — Agents must go through the Metered endpoint — direct relay access still requires x402 payment.

Dashboard

Manage agent keys from Dashboard → Agent Keys.