Home
Documentation / get_started
Page: get_started
⬇ Download Markdown

Wallet4Agent — Getting Started from Zero to Agent

Spin up a brand-new Agent identity + wallet, configure it as a developer, and plug your Agent to the MCP server using PAT or OAuth 2.0 Client Credentials (including private_key_jwt with JWK keys).

This guide explains: how to start from nothing, how to access as a developer, and how to define the client authentication method for your Agent.

🧭 1. Mental model

There are three roles:

  1. Guest
  2. No auth header.

  3. Can bootstrap a new Agent identity + wallet.

  4. Developer (Dev)

  5. Uses a dev_personal_access_token.

  6. Manages configuration, tokens, keys, lifecycle of the Agent wallet.

  7. Agent

  8. Uses either:
    • an Agent Personal Access Token (PAT), or
    • an OAuth 2.0 access token (Client Credentials flow, secret or private_key_jwt).
  9. Calls Agent-level tools (read wallet data, accept credential offers, etc.).

All three talk to the same MCP endpoint:

POST https://wallet4agent.com/mcp
Content-Type: application/json

🚀 2. Zero → Agent in one call (Guest)

As a guest (no auth header), call the tool:

This will:

2.1 Request (no Authorization header)

curl -s https://wallet4agent.com/mcp   -H "Content-Type: application/json"   -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_agent_identifier_and_wallet",
      "arguments": {
        "owners_identity_provider": "google",        // or "github", "personal data wallet"
        "owners_login": "dev@example.com",           // comma-separated list if multiple
        "authentication": "Personal Access Token (PAT)" 
        // or: "OAuth 2.0 Client Credentials Grant"
      }
    }
  }'

2.2 Typical response (excerpt)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "New agent identifier and wallet created. Copy agent personal access token and dev personal access token as they are not stored."
      }
    ],
    "structuredContent": {
      "agent_identifier": "did:web:wallet4agent.com:<id>",
      "wallet_url": "https://wallet4agent.com/did/<id>",
      "dev_personal_access_token": "<dev_pat>",

      // If authentication = "Personal Access Token (PAT)":
      "agent_personal_access_token": "<agent_pat>"

      // If authentication = "OAuth 2.0 Client Credentials Grant":
      // "agent_client_id": "did:web:wallet4agent.com:<id>",
      // "agent_client_secret": "<agent_client_secret>",
      // "authorization_server": "https://wallet4agent.com"
    }
  }
}

✅ Important: copy dev_personal_access_token (and agent_personal_access_token / agent_client_secret if present).
They are not stored in clear text and cannot be retrieved later.

👨‍💻 3. Acting as a Developer (Dev PAT)

From now on, you act as “Dev for this Agent” using:

You can:

3.1 Dev header

export DEV_PAT="<dev_personal_access_token>"

Every dev call:

-H "Authorization: Bearer $DEV_PAT"

3.2 Get configuration

curl -s https://wallet4agent.com/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer $DEV_PAT"   -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_configuration",
      "arguments": {}
    }
  }' | jq

structuredContent will show (depending on implementation):

🔐 4. Choosing the Agent’s client authentication method

You can choose between:

  1. Agent PAT
  2. Simple: Agent uses a Bearer token to call MCP.

  3. Best for prototypes, single environment.

  4. OAuth 2.0 Client Credentials

  5. Agent identified by client_id (Agent DID) + client_secret or private_key_jwt.
  6. Best for production deployments and integration with Authorisation Server policies.

You already chose a default mode when calling create_agent_identifier_and_wallet (authentication argument).

As a dev, you can refine things with:

🔑 5. Option A — Agent PAT only

If you selected:

"authentication": "Personal Access Token (PAT)"

you received:

The Agent simply calls MCP like this:

export AGENT_PAT="<agent_personal_access_token>"

curl -s https://wallet4agent.com/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer $AGENT_PAT"   -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_this_wallet_data",
      "arguments": {}
    }
  }'

Agent-level tools include: - get_this_wallet_data - get_attestations_of_this_wallet - get_attestations_of_another_agent - accept_credential_offer

If you need a new PAT (compromise, rotation):

curl -s https://wallet4agent.com/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer $DEV_PAT"   -d '{
    "jsonrpc": "2.0",
    "id": "rot",
    "method": "tools/call",
    "params": {
      "name": "rotate_personal_access_token",
      "arguments": {
        "for": "agent"   // or "dev"
      }
    }
  }'

Response will include the new PAT in structuredContent — copy it immediately.

🧾 6. Option B — OAuth 2.0 Client Credentials

If you selected:

"authentication": "OAuth 2.0 Client Credentials Grant"

create_agent_identifier_and_wallet returns:

6.1 Get an access token (client_secret_basic / client_secret_post)

Discover token endpoint from the AS URL (example):

export AS_BASE="https://wallet4agent.com"
curl -s $AS_BASE/.well-known/openid-configuration | jq '.token_endpoint'
# -> "https://wallet4agent.com/oauth/token"   (example)

client_secret_post

export CLIENT_ID="did:web:wallet4agent.com:<id>"
export CLIENT_SECRET="<agent_client_secret>"
export TOKEN_ENDPOINT="https://wallet4agent.com/oauth/token"
export RESOURCE="https://wallet4agent.com"

curl -s $TOKEN_ENDPOINT   -d "grant_type=client_credentials"   -d "client_id=$CLIENT_ID"   -d "client_secret=$CLIENT_SECRET"   -d "resource=$RESOURCE" | jq

client_secret_basic

curl -s $TOKEN_ENDPOINT   -u "$CLIENT_ID:$CLIENT_SECRET"   -d "grant_type=client_credentials"   -d "resource=$RESOURCE" | jq

Typical response:

{
  "access_token": "<agent_access_token>",
  "token_type": "Bearer",
  "expires_in": 1800
}

6.2 Use the access token with MCP

export AGENT_ACCESS_TOKEN="<agent_access_token>"

curl -s https://wallet4agent.com/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer $AGENT_ACCESS_TOKEN"   -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_this_wallet_data",
      "arguments": {}
    }
  }'

🔏 7. Option C — OAuth 2.0 with private_key_jwt (JWK)

For stronger security, the Agent can authenticate to the AS using a JWK public key and private_key_jwt:

  1. The Agent holds a private JWK (P-256 / ES256).
  2. As a dev, you register the public JWK in Wallet4Agent via update_configuration.
  3. The Agent obtains access tokens using Client Credentials + client_assertion JWT.

7.1 Dev: register the public JWK

Assume you have:

{
  "kty": "EC",
  "crv": "P-256",
  "x": "...",
  "y": "..."
}

Call:

curl -s https://wallet4agent.com/mcp   -H "Content-Type: application/json"   -H "Authorization: Bearer $DEV_PAT"   -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "update_configuration",
      "arguments": {
        "client_public_key": "{ "kty":"EC", "crv":"P-256", "x":"...", "y":"..." }"
      }
    }
  }' | jq

Wallet4Agent stores this in the wallet (e.g. client_public_key) and the Authorization Server uses it to verify client_assertion JWTs.

7.2 Agent: obtain token with private_key_jwt

High-level flow:

  1. Agent builds a JWT:
  2. iss = CLIENT_ID (Agent DID)
  3. sub = CLIENT_ID
  4. aud = token endpoint URL (https://wallet4agent.com/oauth/token)

  5. signed with its private JWK (ES256).

  6. Agent calls the token endpoint:

curl -s $TOKEN_ENDPOINT   -d "grant_type=client_credentials"   -d "resource=$RESOURCE"   -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer"   -d "client_assertion=<signed_jwt>" | jq
  1. Response:
{
  "access_token": "<agent_access_token>",
  "token_type": "Bearer",
  "expires_in": 1800
}
  1. The Agent then uses Authorization: Bearer <agent_access_token> on MCP just like in 6.2.

🛠 8. Tool overview by role

Guest tools

Developer tools (requires dev_personal_access_token)

Agent tools (Agent PAT or OAuth2 access token)

🔎 9. MCP configuration examples (ChatGPT / VS Code)

9.1 ChatGPT Desktop (HTTP MCP)

~/.config/openai/mcp/servers.json:

{
  "wallet4agent": {
    "transport": {
      "type": "http",
      "url": "https://wallet4agent.com/mcp"
    }
  }
}

9.2 VS Code MCP

.vscode/mcp.json:

{
  "servers": {
    "wallet4agent": {
      "transport": {
        "type": "http",
        "url": "https://wallet4agent.com/mcp"
      }
    }
  }
}

Then use the MCP panel to:

🧰 10. Troubleshooting & tips

Maintainer: Talao • MCP Wallet4Agent
Issues / feedback: via the contact form linked on the home page.