Viatika/Docs

Quickstart — Get Running in 5 Minutes

Prerequisites

  • A Viatika account with an organization
  • An API token (format: vt_live_... or vt_test_...)
  • Your organization ID (UUID)
  • Your entity ID (UUID) — identifies the user or swarm making payments

Step 1: Get an API Token

bash
curl -X POST https://api.viatika.ai/v1/tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <session-token>" \
  -d '{
    "organizationId": "YOUR_ORG_UUID",
    "entityId": "YOUR_ENTITY_UUID",
    "entityType": "individual",
    "name": "My Agent Key",
    "scopes": ["x402:sign", "credits:consume"]
  }'

Response (token shown only once):

json
{
  "token": "vt_live_abc123456789defghijklmnopqrstuvwxyz123456",
  "tokenId": "770e8400-e29b-41d4-a716-446655440003",
  "tokenPrefix": "vt_live_abc12345",
  "message": "⚠️ Save this token now - it will never be shown again!"
}

Save the token. Store it in an environment variable:

bash
export VIATIKA_API_TOKEN="vt_live_abc123..."
export VIATIKA_API_URL="https://api.viatika.ai"
export VIATIKA_ORG_ID="your-org-uuid"
export VIATIKA_ENTITY_ID="your-entity-uuid"

Step 2: Choose Integration Path

Option A: MCP Server (Claude Desktop, Coding Agents)

Build and install the MCP server binary:

bash
cd ~/src/github.com/viatika-ai/platform
go build -o /usr/local/bin/viatika-mcp ./cmd/agent-mcp

Add to your Claude Desktop config (claude_desktop_config.json):

json
{
  "mcpServers": {
    "viatika": {
      "command": "/usr/local/bin/viatika-mcp",
      "env": {
        "VIATIKA_API_URL": "https://api.viatika.ai",
        "VIATIKA_API_TOKEN": "vt_live_abc123...",
        "VIATIKA_ORG_ID": "your-org-uuid",
        "VIATIKA_ENTITY_ID": "your-entity-uuid"
      }
    }
  }
}

Restart Claude Desktop. You now have two tools:

  • pay_for_resource — make HTTP requests with automatic 402 handling
  • check_balance — check remaining credits

Option B: REST API (Any HTTP Client)

No binary required. Call the API directly with curl, Python, JavaScript, etc.

Set your env vars:

bash
export VIATIKA_API_TOKEN="vt_live_abc123..."
export VIATIKA_API_URL="https://api.viatika.ai"
export VIATIKA_ORG_ID="your-org-uuid"
export VIATIKA_ENTITY_ID="your-entity-uuid"

Step 3: Make Your First Payment

Using MCP (Option A)

In Claude Desktop, ask:

“Fetch https://api.example.com/paid-resource using pay_for_resource”

Claude will call the tool, handle any 402 automatically, and return the response.

Using REST API (Option B)

3a. Try the target URL directly

bash
curl -s https://api.example.com/paid-resource

If the service requires payment, you get:

http
HTTP/1.1 402 Payment Required

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "1500000",
      "payTo": "0xSERVICE_PROVIDER_ADDRESS",
      "maxTimeoutSeconds": 60
    }
  ],
  "resource": {
    "url": "https://api.example.com/paid-resource",
    "description": "Premium API access"
  }
}

3b. Sign the payment through Viatika

Take the entire 402 response body and send it to Viatika:

bash
curl -X POST "${VIATIKA_API_URL}/v1/x402/sign-payment" \
  -H "Authorization: Bearer ${VIATIKA_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentRequired": {
      "x402Version": 2,
      "accepts": [
        {
          "scheme": "exact",
          "network": "eip155:8453",
          "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "amount": "1500000",
          "payTo": "0xSERVICE_PROVIDER_ADDRESS",
          "maxTimeoutSeconds": 60
        }
      ]
    },
    "organizationId": "'${VIATIKA_ORG_ID}'",
    "entityId": "'${VIATIKA_ENTITY_ID}'",
    "entityType": "individual",
    "providerId": "api.example.com"
  }'

Response (approved):

json
{
  "approved": true,
  "signature": {
    "v": 28,
    "r": "0x1234...abcd",
    "s": "0x5678...ef01"
  },
  "authorization": {
    "from": "0xVIATIKA_WALLET",
    "to": "0xSERVICE_PROVIDER",
    "value": "1500000",
    "validAfter": "0",
    "validBefore": "1769917810",
    "nonce": "0xRANDOM_NONCE_32_BYTES"
  },
  "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "creditRemaining": 8500
}

3c. Retry with payment headers

bash
curl https://api.example.com/paid-resource \
  -H "X-Payment: <base64-encoded-payment-payload>" \
  -H "X-Payment-Signature: 0x<r><s><v-hex>"

The service verifies the signature, submits the USDC transfer on-chain, and returns your data.

Step 4: Check Your Balance

MCP

Ask Claude: “Check my Viatika balance”

REST API

bash
curl "${VIATIKA_API_URL}/v1/accounts/${VIATIKA_ORG_ID}" \
  -H "Authorization: Bearer ${VIATIKA_API_TOKEN}"

Response:

json
{
  "id": "account-uuid",
  "organizationId": "your-org-uuid",
  "balance": 8500,
  "lowBalanceThreshold": 1000,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T12:30:00Z"
}

Balance is in credits. 1 credit = $0.001. So 8500 credits = $8.50.

Next Steps