Skip to main content

​
Quick Start

What You’ll LearnIn this guide, you’ll:
  • Get your API key from the dashboard
  • Create a user and initiate KYC verification
  • Create an agent for your AI workflow
  • Issue your first virtual card
  • Retrieve card credentials for a purchase
Time to complete: 5 minutes
This guide will walk you through creating your first virtual card with Proxy.

​
Prerequisites

  • A Proxy account (sign up here)
  • An API key from your dashboard

​
Step 1: Get Your API Key

1

Log into Dashboard

Go to app.useproxy.ai and sign in.
2

Create API Key

Navigate to Settings > API Keys and click Create Key.
3

Copy Your Key

Copy your API key. It starts with lk_dev_ for sandbox or lk_live_ for production.
Keep your API key secure. Never expose it in client-side code or commit it to version control.

​
Step 2: Create a User

Users fund card spending. Start by creating a user: 
curl -X POST https://api.useproxy.ai/v1/users \
  -H "Api-Key: lk_dev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  }'

{
  "object": "user",
  "id": "user_abc123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "applicationStatus": "notStarted"
}

​
Step 3: Initiate KYC Verification

The user must complete KYC before using cards: 
curl -X POST https://api.useproxy.ai/v1/verification/user \
  -H "Api-Key: lk_dev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_abc123"
  }'

{
  "object": "verification",
  "userId": "user_abc123",
  "applicationStatus": "pending",
  "verificationUrl": "https://kyc.useproxy.ai/verify/xyz789"
}
The user must complete KYC via the verificationUrl before they can use cards.

​
Step 4: Register an Agent

Once the user is approved, register an agent.
Why register an agent? Agents are the identity layer between users (who fund) and cards (which spend). A user can have multiple agents - whether that’s different AI assistants, sub-agents, or separate workflows:
  • Each agent gets its own spending limits and cards
  • Track spending per agent separately
  • Suspend one agent without affecting others
  • Issue scoped agent tokens instead of sharing your API key
The externalId is your unique identifier for this agent (e.g., a UUID from your system). See Agents concept for more details.
curl -X POST https://api.useproxy.ai/v1/agents/register \
  -H "Api-Key: lk_dev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "userId": "user_abc123",
    "name": "Checkout Agent",
    "description": "Handles online purchases",
    "spendingLimit": 50000,
    "spendingLimitFrequency": "perMonth"
  }'

{
  "object": "agent",
  "id": "agent_xyz789",
  "externalId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "userId": "user_abc123",
  "name": "Checkout Agent",
  "status": "active",
  "spendingLimit": 50000,
  "spendingLimitFrequency": "perMonth",
  "currentSpend": 0,
  "created": true,
  "token": "at_dev_abc123..."
}
The token is only returned on first registration. Store it securely if you want your agent to authenticate directly.

​
Step 5: Issue a Card

Now create a virtual card for the agent: 
curl -X POST https://api.useproxy.ai/v1/agents/agent_xyz789/cards \
  -H "Api-Key: lk_dev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "Purchase office supplies from Amazon",
    "type": "single",
    "maxAmount": 10000
  }'

{
  "object": "card",
  "id": "card_def456",
  "agentId": "agent_xyz789",
  "userId": "user_abc123",
  "status": "active",
  "last4": "4242",
  "purpose": "Purchase office supplies from Amazon",
  "type": "single",
  "maxAmount": 10000
}

​
Step 6: Get Card Details

To make a purchase, retrieve the card credentials: 
curl -X POST https://api.useproxy.ai/v1/cards/card_def456/details \
  -H "Api-Key: lk_dev_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Purchase office supplies from Amazon",
    "expectedAmount": 5000,
    "merchantText": "Amazon"
  }'

{
  "accessEventId": "evt_123",
  "pan": "4111111111111111",
  "cvv": "123",
  "expirationMonth": "12",
  "expirationYear": "2025",
  "last4": "1111"
}
The accessEventId creates an audit trail linking this credential access to your attestation.

​
Step 7: Card Lifecycle

After use, manage your card with action endpoints: 
# Freeze the card
curl -X POST https://api.useproxy.ai/v1/cards/card_def456/freeze \
  -H "Api-Key: lk_dev_your_api_key"

# Unfreeze the card
curl -X POST https://api.useproxy.ai/v1/cards/card_def456/unfreeze \
  -H "Api-Key: lk_dev_your_api_key"

# Close the card permanently
curl -X POST https://api.useproxy.ai/v1/cards/card_def456/close \
  -H "Api-Key: lk_dev_your_api_key"

​
Troubleshooting

Check:
  • Verify the key in your dashboard matches what you’re using
  • Ensure you’re using lk_dev_ for sandbox, lk_live_ for production
  • Check for extra whitespace or newlines in the key
Cause: KYC may require manual review or document re-upload.Solution: Check verification status via API:
curl https://api.useproxy.ai/v1/verification/user/$USER_ID \
  -H "Api-Key: $API_KEY"
Cause: User’s available balance is less than card’s maxAmount.Solution: Check balance and either reduce maxAmount or have user deposit more funds:
curl https://api.useproxy.ai/v1/balances/$USER_ID \
  -H "Api-Key: $API_KEY"

​
Next Steps

System Overview

Understand the full architecture

Payment Flow

Complete payment lifecycle walkthrough

Card Types

Understand single vs multi cards

Webhooks

Set up real-time notifications