Agent Service Keys

Let agents pay for APIs — without wallets.

Agents use a simple API key. RelAI handles payments, settlement, and billing automatically.

The agent never touches crypto. Payments are executed by RelAI using your Metered account.

10-second example

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

→ 200 OK
→ payment handled by RelAI
AgentAPI402RelAI paysAPI returns 200

The agent passes two headers. RelAI identifies it, finds the Metered account, and pays the x402 fee automatically.

Why this exists

Without Agent Keys
✗ agents need wallets
✗ agents manage private keys
✗ payments require signing logic
✗ crypto setup on every deploy
With RelAI Agent Keys
no wallets
no crypto handling
no signing logic
just an API key

How it works

01You prove ownership of the agent (ERC-721 NFT) — one-time, no gas required
02RelAI issues a service key (sk-agent-...) tied to your account and agent ID
03Agent makes API calls with two headers: X-Service-Key and X-Agent-ID
04RelAI pays for each request automatically from your Metered account

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

Calling APIs as an agent

Agents call APIs through the Metered endpoint. RelAI handles x402 payment automatically.

Metered Relay — any RelAI-hosted API

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

Metered Proxy — any external x402 API

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

Agent bootstrapping

The agent is configured at startup — the same way any API credential is passed (OpenAI key, DB URL, etc.).

Environment variables

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

Config file

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

Tip: The consent flow is only needed once per agent. After the key is issued, the agent stores and reuses it — no re-authentication required.

OAuth consent flow (advanced)

For autonomous agents that cannot open a browser. The agent requests access, the user approves via a link, and the agent retrieves the key — without ever seeing user credentials.

1
Agent calls /consent/initiate
Returns consentToken + authorizeUrl
2
User opens authorizeUrl and clicks Allow
One-click approval, no wallet signing
3
Agent polls /consent/status/:token
Waits for status: approved + retrieveNonce
4
Agent signs retrieveNonce and calls /consent/retrieve
Key delivered only to the keypair that initiated the flow

1. Initiate

POST /agent-keys/consent/initiate
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"
  }'

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

3. Poll for approval

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

Statuses: consent_pending · approved · rejected · expired · retrieved

4. Retrieve the key

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

POST/agent-keys/consent/initiatePublic

Start the consent flow. Returns consentToken and authorizeUrl.

GET/agent-keys/consent/status/:tokenPublic

Poll consent status. Returns retrieveNonce when approved.

POST/agent-keys/consent/retrievePublic

Retrieve the service key. Requires agent signature of retrieveNonce.

GET/agent-keysBearer JWT

List all agent keys linked to your account.

DELETE/agent-keys/:keyIdBearer JWT

Revoke an agent key permanently. Immediate effect.

Security

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.
Revocable at any time — One click in the dashboard removes the key permanently — effective immediately.
No credential exposure — The agent never sees your private key or your RelAI JWT token.

Dashboard

Manage agent keys from Dashboard → Agent Keys.

Link Agent

Enter contract address, token ID, and network. Connect MetaMask and sign the challenge (no gas). Key issued immediately.

Revoke Key

Click the trash icon next to a key. Confirmation dialog appears before permanent deletion. Effective immediately.

Go to Agent Keys Metered API docs
SDK referenceFacilitatorSDK Plugins
    Agent Service Keys — Let agents pay without wallets | RelAI Documentation | RelAI