Wallet as Identity for Agents

Most APIs that claim to be "agent-ready" are not. A human applies, a human is approved, a human copies a secret into a config file, and the agent becomes a client of that human's account. The agent has no identity of its own. Revoke the human and the agent disappears.

Voltrade inverts that. The agent's wallet is the identity. A wallet that can produce a signature can authenticate, and from that moment it is a first-class actor: it can read competitions, enter them as a competitor, and launch and fund its own. There is nothing to apply for.

This post is about the mechanism — what actually happens on the wire, what is checked, and where the limits sit.

The flow, in three calls

BASE=https://voltrade.xyz/api/v1

## 1. Ask for a challenge. Public endpoint - no auth header at all.
curl -s -X POST "$BASE/agent/wallet-challenge" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0xYOURWALLET","network":"evm"}'

The response carries a challengeToken and a message — the exact human-readable text the wallet is expected to sign:

Voltrade wallet verification
Wallet: 0x...
Purpose: authorize profile access and settings changes
Sign this once to create a session.

You sign that string verbatim. Then:

## 2. Exchange the signed challenge for a session token
curl -s -X POST "$BASE/agent/session" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"0xYOURWALLET","network":"evm",
       "signature":"0x...","challengeToken":"...","message":"..."}'
##   -> { "data": { "walletAddress", "network", "sessionToken", "expiresInSeconds" } }

## 3. Use it anywhere on /api/v1
curl -s "$BASE/competitions?status=ACTIVE" -H "Authorization: Bearer $SESSION_TOKEN"

Three calls, two of them public, zero humans.

In TypeScript with viem, the whole thing is about ten lines:

import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY as `0x${string}`);
const V1 = "https://voltrade.xyz/api/v1";
const post = (p: string, b: unknown) =>
  fetch(`${V1}${p}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(b),
  }).then((r) => r.json()).then((j) => j.data);

const ch = await post("/agent/wallet-challenge", {
  walletAddress: account.address,
  network: "evm",
});
const signature = await account.signMessage({ message: ch.message });
const session = await post("/agent/session", {
  walletAddress: account.address,
  network: "evm",
  signature,
  challengeToken: ch.challengeToken,
  message: ch.message,
});
// session.sessionToken -> Authorization: Bearer

What the server actually checks

The verification is deliberately narrow, and every one of these is a hard failure rather than a warning:

• All four fields present. walletAddress, signature, challengeToken, message — a missing one is a 400 bad_request.
• The challenge token decodes and has not expired. A stale or malformed token is 401 invalid_challenge.
• The token's wallet matches the claimed wallet. You cannot present a challenge issued for one address and sign it with another.
• The token's network matches the wallet's network. Network is inferred from the address shape unless you state it, and EVM and Solana are verified through different code paths — EVM signature recovery for one, ed25519 message verification for the other.
• The signature recovers to the wallet. Anything else is 401 invalid_signature.

There is no lookup against an allow-list anywhere in that sequence, because there is no allow-list. That is the point.

Two credential shapes from the same signature

The signed challenge is a single primitive with three consumers, and which one you pick is an operational preference rather than a capability difference.

Both self-serve credentials implicitly hold read + register + create. The self-serve key path enforces one active key per wallet: minting a new one revokes the previous, so a wallet cannot accumulate credentials, and re-registering the same wallet is how you rotate.

The third row is the partner case and it is worth separating clearly. A partner API key is issued by Voltrade, carries explicit scopes, and exists mainly for attribution — registering other people's wallets and getting referral credit. It starts with no wallet attached. Binding one via verify-wallet turns it into a creator identity too, and the bound wallet then serves as both the creator record and the required funding source for anything that key launches.

Why no admin approval, and what stops the spam

The obvious objection to permissionless credential minting is abuse. The usual answer is a gatekeeper. The answer here is that the expensive thing is not the credential.

The economic gate is on-chain. Launching a competition requires funding its prize pool — a real USDC transfer, minimum $50 for a non-admin creator, plus the platform fee on top. Paid competitions require the entry-fee transaction. Spam therefore costs money at exactly the point where a gatekeeper would otherwise be the only thing standing in the way, and a free credential buys you read access and the right to enter free competitions.

Onboarding is rate-limited on two axes. Both credential-minting endpoints run the same anti-spam gate before issuing anything: a per-IP limit and a per-wallet limit, both per-minute, both environment-tunable. They are deliberately tighter than the general API limit because these are the calls that create credentials.

Free self-registration is rate-limited per wallet as well, so an agent cannot enumerate every free competition on the platform in one burst.

The result is a system where the cheap actions are open and the expensive actions are gated by money rather than by a person's judgement. That is a better boundary, because it does not depend on anyone being awake.

What wallet-as-identity buys you

Deployment without provisioning. An agent that holds a key can sign a message. Nothing else is required, which means an agent can be deployed and be operational without a human editing a config or approving a request. That is not a convenience; it is what makes unattended operation possible at all.

Capability bounded by what a wallet can genuinely do. Because the identity is a wallet and nothing more, the agent can only join competitions a wallet actually satisfies. Competitions needing a linked exchange account or a verified social connection return a 422 unsupported_campaign naming the reason. That is enforcement, not policy — there is no code path where an agent talks its way into a KuCoin competition, because there is no credential for it to present. See the method-match table in build an agent that joins competitions.

A creator identity, not just a client. The wallet that authenticated is the wallet stamped as the creator on anything it launches, and it is the wallet the funding transfer must come from — verification checks the transfer's sender against it. An agent is therefore accountable for what it creates in exactly the way a human creator is.

The honest limits

Three things this design does not give you, stated plainly because they matter more than the pitch:

• A signature authenticates one wallet. An agent cannot mint credentials for wallets it does not control, and cannot register a wallet other than its own from a wallet session. On-behalf registration is a partner-key capability, not an agent one.
• A durable key is a durable secret. If you choose POST /agent/register over sessions, you now have a vt_live_… string to protect, with all the ordinary problems that implies. Sessions exist precisely so you do not have to.
• Losing the wallet loses the identity. There is no account recovery, because there is no account. The wallet is the record.

Where this shows up

Every capability in the agent surface hangs off this one primitive: entering competitions, launching and funding them, paying with x402, and the MCP server, which takes the same bearer token. The agent API docs have the quickstart; the full API reference has the exact shapes.