# Get an access event
Source: https://docs.useproxy.ai/api-reference/access-events/get-an-access-event
openapi.json get /access-events/{accessEventId}
Retrieve an access event by ID.
# List card access events
Source: https://docs.useproxy.ai/api-reference/access-events/list-card-access-events
openapi.json get /cards/{cardId}/access-events
Retrieve access events (credential access grants) for a card.
# Request card access
Source: https://docs.useproxy.ai/api-reference/access-events/request-card-access
openapi.json post /cards/{cardId}/access
Request access to card credentials. Returns granted/denied status based on policy evaluation.
# Create or register an agent
Source: https://docs.useproxy.ai/api-reference/agents/create-or-register-an-agent
openapi.json post /agents
Create a new agent or register an existing one by externalId (idempotent by externalId).
# Delete an agent
Source: https://docs.useproxy.ai/api-reference/agents/delete-an-agent
openapi.json delete /agents/{agentId}
Soft-delete an agent. Sets status to disabled.
# Get an agent
Source: https://docs.useproxy.ai/api-reference/agents/get-an-agent
openapi.json get /agents/{agentId}
Retrieve an agent by ID.
# List agents
Source: https://docs.useproxy.ai/api-reference/agents/list-agents
openapi.json get /agents
Retrieve a paginated list of agents, optionally filtered by customer.
# Update an agent
Source: https://docs.useproxy.ai/api-reference/agents/update-an-agent
openapi.json patch /agents/{agentId}
Update agent details, status, limits, or policy.
# Authentication
Source: https://docs.useproxy.ai/api-reference/authentication
Authenticate with the Proxy API
# Authentication
All API requests require authentication using a Bearer token.
## API Keys
Get your API key from the [Proxy Dashboard](https://dashboard.useproxy.ai).
Keep your API keys secure. Never expose them in client-side code or public repositories.
## Using Your API Key
Include your API key in the `Authorization` header:
```bash theme={"system"}
curl https://api.useproxy.ai/v1/customers \
-H "Authorization: Bearer sk_live_xxxxx"
```
## Test vs Live Keys
| Key Prefix | Environment |
| ---------- | ---------------------------------- |
| `sk_test_` | Test mode - no real transactions |
| `sk_live_` | Live mode - real card transactions |
## Test Mode
Use test mode keys to develop and test your integration without processing real transactions.
```bash theme={"system"}
# Test mode request
curl https://api.useproxy.ai/v1/customers \
-H "Authorization: Bearer sk_test_xxxxx"
```
Test mode:
* Creates test customers and cards
* Simulates transactions
* No real money movement
## Key Security
Best practices for API key security:
1. **Never commit keys** - Use environment variables
2. **Rotate regularly** - Generate new keys periodically
3. **Limit scope** - Use separate keys for different environments
4. **Monitor usage** - Check API logs for unexpected activity
## Revoking Keys
If a key is compromised, revoke it immediately from the dashboard:
1. Go to Settings → API Keys
2. Click the key to revoke
3. Confirm revocation
Revoked keys immediately stop working.
## Next Steps
Make your first API call
Full API documentation
# Get customer balances
Source: https://docs.useproxy.ai/api-reference/balances/get-customer-balances
openapi.json get /customers/{customerId}/balances
Retrieve the balance information for a customer.
# Get funding instructions
Source: https://docs.useproxy.ai/api-reference/balances/get-funding-instructions
openapi.json get /customers/{customerId}/funding-instructions
Retrieve deposit address and instructions for funding a customer account.
# Close a card
Source: https://docs.useproxy.ai/api-reference/cards/close-a-card
openapi.json delete /cards/{cardId}
Cancel/close a card. The card will no longer be usable for transactions.
# Create a card
Source: https://docs.useproxy.ai/api-reference/cards/create-a-card
openapi.json post /cards
Issue a new virtual or physical card for a customer.
# Freeze a card
Source: https://docs.useproxy.ai/api-reference/cards/freeze-a-card
openapi.json post /cards/{cardId}/freeze
Temporarily freeze a card. The card cannot be used for transactions until unfrozen.
# Get a card
Source: https://docs.useproxy.ai/api-reference/cards/get-a-card
openapi.json get /cards/{cardId}
Retrieve card details by ID.
# Get card details (PAN, CVV)
Source: https://docs.useproxy.ai/api-reference/cards/get-card-details-pan-cvv
openapi.json post /cards/{cardId}/details
Retrieve sensitive card details (PAN, CVV) after policy evaluation. Requires intent if policy mandates it.
# Get card policy summary
Source: https://docs.useproxy.ai/api-reference/cards/get-card-policy-summary
openapi.json get /cards/{cardId}/policy
Retrieve the resolved policy, spend limits, TTL, and cooldown status for a card.
# List cards
Source: https://docs.useproxy.ai/api-reference/cards/list-cards
openapi.json get /cards
Retrieve a paginated list of cards, optionally filtered by customer or agent.
# Replace a card
Source: https://docs.useproxy.ai/api-reference/cards/replace-a-card
openapi.json post /cards/{cardId}/replace
Replace a virtual card with new credentials (new PAN/CVV).
# Unfreeze a card
Source: https://docs.useproxy.ai/api-reference/cards/unfreeze-a-card
openapi.json post /cards/{cardId}/unfreeze
Reactivate a frozen card.
# Update a card
Source: https://docs.useproxy.ai/api-reference/cards/update-a-card
openapi.json patch /cards/{cardId}
Update card status, limits, billing, or policy.
# Create a customer
Source: https://docs.useproxy.ai/api-reference/customers/create-a-customer
openapi.json post /customers
Create a new customer record.
# Delete a customer
Source: https://docs.useproxy.ai/api-reference/customers/delete-a-customer
openapi.json delete /customers/{customerId}
Soft-delete a customer. Sets status to deleted.
# Get a customer
Source: https://docs.useproxy.ai/api-reference/customers/get-a-customer
openapi.json get /customers/{customerId}
Retrieve a customer by ID.
# List customers
Source: https://docs.useproxy.ai/api-reference/customers/list-customers
openapi.json get /customers
Retrieve a paginated list of all customers.
# Update a customer
Source: https://docs.useproxy.ai/api-reference/customers/update-a-customer
openapi.json patch /customers/{customerId}
Update customer details.
# Approve an intent
Source: https://docs.useproxy.ai/api-reference/intents/approve-an-intent
openapi.json post /intents/{intentId}/approve
Approve a pending_approval intent, allowing the associated transaction to proceed.
# Cancel an intent
Source: https://docs.useproxy.ai/api-reference/intents/cancel-an-intent
openapi.json delete /intents/{intentId}
Cancel/delete a pending intent.
# Create an intent
Source: https://docs.useproxy.ai/api-reference/intents/create-an-intent
openapi.json post /cards/{cardId}/intents
Declare an intent to spend before accessing card credentials.
# Get an intent
Source: https://docs.useproxy.ai/api-reference/intents/get-an-intent
openapi.json get /intents/{intentId}
Retrieve an intent by ID.
# Get intent findings
Source: https://docs.useproxy.ai/api-reference/intents/get-intent-findings
openapi.json get /intents/{intentId}/findings
Retrieve policy findings/analysis for an intent.
# List card intents
Source: https://docs.useproxy.ai/api-reference/intents/list-card-intents
openapi.json get /cards/{cardId}/intents
Retrieve intents associated with a card.
# Reject an intent
Source: https://docs.useproxy.ai/api-reference/intents/reject-an-intent
openapi.json post /intents/{intentId}/reject
Reject a pending_approval intent.
# API Introduction
Source: https://docs.useproxy.ai/api-reference/introduction
Overview of the Proxy API
# API Reference
The Proxy API enables you to programmatically manage customers, agents, cards, and transactions.
## Base URL
```
https://api.useproxy.ai/v1
```
## Request Format
All requests use JSON bodies and require the `Content-Type: application/json` header.
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/customers \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{"type": "consumer", "email": "alice@example.com"}'
```
## Response Format
Responses are JSON with consistent structure:
```json theme={"system"}
{
"id": "cust_xxx",
"type": "consumer",
"email": "alice@example.com",
"createdAt": "2024-01-15T10:30:00Z"
}
```
## Errors
Errors return appropriate HTTP status codes with details:
```json theme={"system"}
{
"error": {
"code": "invalid_request",
"message": "Email is required"
}
}
```
| Status | Description |
| ------ | ---------------------------------- |
| 400 | Bad request - invalid parameters |
| 401 | Unauthorized - invalid API key |
| 404 | Not found - resource doesn't exist |
| 429 | Rate limited - too many requests |
| 500 | Server error |
## Idempotency
For POST requests, include an `Idempotency-Key` header to ensure operations are only performed once:
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
-H "Authorization: Bearer your_api_key" \
-H "Idempotency-Key: unique-request-id" \
-d '{"customerId": "cust_xxx"}'
```
Idempotency keys are cached for 24 hours.
## Pagination
List endpoints support pagination:
```bash theme={"system"}
curl "https://api.useproxy.ai/v1/transactions?limit=10&cursor=cur_xxx" \
-H "Authorization: Bearer your_api_key"
```
Response includes pagination info:
```json theme={"system"}
{
"data": [...],
"hasMore": true,
"nextCursor": "cur_yyy"
}
```
## Rate Limits
| Tier | Requests/minute |
| ---------- | --------------- |
| Standard | 100 |
| Pro | 1000 |
| Enterprise | Custom |
## Next Steps
Set up API authentication
Make your first API call
# Create a KYC application
Source: https://docs.useproxy.ai/api-reference/kyc/create-a-kyc-application
openapi.json post /kyc/applications
Submit a new KYC application for a customer.
# Get a KYC application
Source: https://docs.useproxy.ai/api-reference/kyc/get-a-kyc-application
openapi.json get /kyc/applications/{applicationId}
Retrieve a KYC application by ID.
# List KYC applications
Source: https://docs.useproxy.ai/api-reference/kyc/list-kyc-applications
openapi.json get /kyc/applications
Retrieve KYC applications for a customer.
# Update a KYC application
Source: https://docs.useproxy.ai/api-reference/kyc/update-a-kyc-application
openapi.json patch /kyc/applications/{applicationId}
Update a KYC application with additional information.
# Evaluate spend policy
Source: https://docs.useproxy.ai/api-reference/spend/evaluate-spend-policy
openapi.json post /spend/evaluate
Evaluate whether a proposed spend would be approved based on current policy rules.
# Get a dispute
Source: https://docs.useproxy.ai/api-reference/transactions/get-a-dispute
openapi.json get /disputes/{disputeId}
Retrieve a dispute by ID.
# Get a transaction
Source: https://docs.useproxy.ai/api-reference/transactions/get-a-transaction
openapi.json get /transactions/{transactionId}
Retrieve a transaction by ID.
# List disputes
Source: https://docs.useproxy.ai/api-reference/transactions/list-disputes
openapi.json get /disputes
Retrieve a list of disputes.
# List transactions
Source: https://docs.useproxy.ai/api-reference/transactions/list-transactions
openapi.json get /transactions
Retrieve a paginated list of transactions, optionally filtered by customer, agent, or card.
# Update a transaction
Source: https://docs.useproxy.ai/api-reference/transactions/update-a-transaction
openapi.json patch /transactions/{transactionId}
Update transaction memo.
# Create or update a webhook
Source: https://docs.useproxy.ai/api-reference/webhooks/create-or-update-a-webhook
openapi.json post /webhooks
Create a new webhook subscription or update an existing one (if id is provided).
# Delete a webhook
Source: https://docs.useproxy.ai/api-reference/webhooks/delete-a-webhook
openapi.json delete /webhooks/{webhookId}
Disable a webhook subscription.
# Get a webhook
Source: https://docs.useproxy.ai/api-reference/webhooks/get-a-webhook
openapi.json get /webhooks/{webhookId}
Retrieve a webhook subscription by ID.
# List webhook subscriptions
Source: https://docs.useproxy.ai/api-reference/webhooks/list-webhook-subscriptions
openapi.json get /webhooks
Retrieve all configured webhook subscriptions.
# Agents
Source: https://docs.useproxy.ai/concepts/agents
Autonomous actors that spend on behalf of customers
# Agents
An **Agent** is an autonomous actor (AI or automation) that spends on behalf of a customer. Agents can be assigned cards and must declare intents before making purchases.
## Creating an Agent
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/agents \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"externalId": "my-agent-123",
"name": "Shopping Agent"
}'
```
## Agent Fields
| Field | Type | Description |
| ------------ | ------ | ------------------------------------ |
| `customerId` | string | The customer this agent belongs to |
| `externalId` | string | Your unique identifier for the agent |
| `name` | string | Human-readable name |
| `status` | string | `active` or `suspended` |
## Agent Status
| Status | Description |
| ----------- | ------------------------------------------ |
| `active` | Agent can access cards and make purchases |
| `suspended` | Agent is temporarily blocked from spending |
## Policy Overrides
Agents can have policy overrides that take precedence over customer defaults:
```json theme={"system"}
{
"policy": {
"requireIntent": true,
"limits": {
"perAuth": 5000
},
"blockedMccs": ["7995"]
}
}
```
## Suspend an Agent
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/agents/agent_xxx/suspend \
-H "Authorization: Bearer your_api_key"
```
## Next Steps
Issue cards to agents
Declare purchase intents
# Cards
Source: https://docs.useproxy.ai/concepts/cards
Virtual spending instruments with policy controls
# Cards
A **Card** is a virtual spending instrument issued to an agent. Cards have policy controls that determine how they can be used.
## Card Types
| Usage | Description |
| -------- | ------------------------------------------------- |
| `single` | One-time use, auto-closes after first transaction |
| `multi` | Reusable for multiple transactions |
## Creating a Card
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"agentId": "agent_xxx",
"usage": "multi"
}'
```
## Card Fields
| Field | Type | Description |
| ------------ | ------ | ------------------------------ |
| `customerId` | string | Owner of the card |
| `agentId` | string | Agent assigned to use the card |
| `usage` | string | `single` or `multi` |
| `status` | string | Card status |
## Card Status
| Status | Description |
| -------- | --------------------------------- |
| `active` | Card can be used for transactions |
| `frozen` | Temporarily blocked |
| `closed` | Permanently deactivated |
## Policy Controls
Cards can have their own policy overrides:
```json theme={"system"}
{
"policy": {
"maxAmount": 10000,
"allowedMerchants": ["amazon.com"],
"lockToFirstMerchant": true
}
}
```
## Accessing Card Details
Card credentials are retrieved via the details endpoint after declaring an intent:
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/details \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"intentId": "int_xxx",
"purpose": "Purchase supplies"
}'
```
Response:
```json theme={"system"}
{
"pan": "4111111111111111",
"exp": "12/28",
"cvv": "123"
}
```
## Card Actions
### Freeze a Card
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/freeze \
-H "Authorization: Bearer your_api_key"
```
### Unfreeze a Card
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/unfreeze \
-H "Authorization: Bearer your_api_key"
```
### Close a Card
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/close \
-H "Authorization: Bearer your_api_key"
```
## Next Steps
Declare purchase intents
Get real-time notifications
# Customers
Source: https://docs.useproxy.ai/concepts/customers
The entity who owns funds and cards
# Customers
A **Customer** is the entity responsible for funding card spending. Customers can be individuals (consumers) or businesses (corporate).
## Customer Types
| Type | Description |
| ----------- | ----------------- |
| `consumer` | Individual person |
| `corporate` | Business entity |
## Creating a Customer
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/customers \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"type": "consumer",
"email": "alice@example.com",
"name": { "first": "Alice", "last": "Smith" }
}'
```
## Customer Fields
| Field | Type | Description |
| -------- | ------ | ----------------------------------------------------------- |
| `type` | string | `consumer` or `corporate` |
| `email` | string | Customer email address |
| `name` | object | First and last name (consumer) or business name (corporate) |
| `status` | string | KYC verification status |
## KYC Verification
Customers must complete KYC (Know Your Customer) verification before issuing cards. The verification status can be:
* `pending` - Awaiting verification
* `verified` - Approved for card issuance
* `rejected` - Verification failed
## Default Policies
Customers can set default spending policies that apply to all their agents and cards unless overridden.
```json theme={"system"}
{
"policy": {
"requireIntent": true,
"autoApproveBelow": 10000,
"limits": {
"perDay": 50000
}
}
}
```
## Next Steps
Create agents to spend on behalf of customers
Issue virtual cards
# Disputes
Source: https://docs.useproxy.ai/concepts/disputes
Contesting transactions and resolving chargebacks
# Disputes
A **Dispute** is a formal challenge to a transaction. Disputes occur when a cardholder believes a transaction was unauthorized, incorrect, or the goods/services were not delivered.
## What Triggers a Dispute
Disputes can be initiated for several reasons:
| Reason | Description |
| ---------------------- | ----------------------------------------------- |
| `unauthorized` | Cardholder did not authorize the transaction |
| `fraud` | Suspected fraudulent activity |
| `not_received` | Goods or services were not received |
| `not_as_described` | Product/service differs from what was described |
| `duplicate` | Charged multiple times for the same purchase |
| `incorrect_amount` | Transaction amount is wrong |
| `canceled` | Recurring charge after cancellation |
| `credit_not_processed` | Refund not received |
## Dispute Statuses
| Status | Description |
| -------------- | ------------------------------------- |
| `open` | Dispute filed, awaiting action |
| `under_review` | Evidence submitted, being reviewed |
| `resolved` | Dispute closed (won or lost) |
| `won` | Dispute decided in cardholder's favor |
| `lost` | Dispute decided in merchant's favor |
## Dispute Lifecycle
```
Transaction Contested → open → Evidence Submitted → under_review → Resolved (won/lost)
```
Cardholder identifies an issue with a transaction and files a dispute.
* Dispute is created with status `open`
* Provisional credit may be issued
* Merchant is notified
Both parties can submit evidence to support their case.
* Transaction details and receipts
* Communication records
* Delivery confirmation
* Terms and conditions accepted
The card network reviews the evidence and makes a determination.
* Status changes to `under_review`
* Typical review period: 30-90 days
* Additional information may be requested
The dispute is resolved in favor of either the cardholder or merchant.
* `won`: Cardholder keeps the credit
* `lost`: Credit is reversed; funds returned to merchant
## Filing a Dispute
### Create a Dispute
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/disputes \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"transactionId": "txn_abc123",
"reason": "not_received",
"description": "Order never arrived despite tracking showing delivered"
}'
```
Response:
```json theme={"system"}
{
"id": "dsp_xyz789",
"transactionId": "txn_abc123",
"customerId": "cust_xxx",
"cardId": "card_yyy",
"status": "open",
"reason": "not_received",
"description": "Order never arrived despite tracking showing delivered",
"amount": 4500,
"currency": "USD",
"createdAt": "2024-01-15T10:30:00Z"
}
```
### Dispute Fields
| Field | Type | Description |
| --------------- | ------ | -------------------------- |
| `transactionId` | string | Transaction being disputed |
| `reason` | string | Dispute reason code |
| `description` | string | Detailed explanation |
## Viewing Disputes
### List All Disputes
```bash theme={"system"}
curl https://api.useproxy.ai/v1/disputes \
-H "Authorization: Bearer your_api_key"
```
Response:
```json theme={"system"}
{
"disputes": [
{
"id": "dsp_xyz789",
"transactionId": "txn_abc123",
"status": "under_review",
"reason": "not_received",
"amount": 4500,
"currency": "USD",
"createdAt": "2024-01-15T10:30:00Z"
}
]
}
```
### Filter by Status
```bash theme={"system"}
curl "https://api.useproxy.ai/v1/disputes?status=open" \
-H "Authorization: Bearer your_api_key"
```
### Get Single Dispute
```bash theme={"system"}
curl https://api.useproxy.ai/v1/disputes/dsp_xyz789 \
-H "Authorization: Bearer your_api_key"
```
Response:
```json theme={"system"}
{
"id": "dsp_xyz789",
"transactionId": "txn_abc123",
"customerId": "cust_xxx",
"cardId": "card_yyy",
"status": "under_review",
"reason": "not_received",
"description": "Order never arrived despite tracking showing delivered",
"amount": 4500,
"currency": "USD",
"creditAmount": 4500,
"evidence": {
"submitted": true,
"submittedAt": "2024-01-16T14:00:00Z"
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-16T14:00:00Z"
}
```
## Evidence Submission
Submit evidence to support a dispute claim.
### Submit Text Evidence
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/disputes/dsp_xyz789/evidence \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"textEvidence": "Order #12345 was placed on Jan 10. Tracking number 1Z999AA10123456784 shows delivered on Jan 12, but package was not at delivery location. Building security confirmed no package was received."
}'
```
### Submit Document Evidence
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/disputes/dsp_xyz789/evidence \
-H "Authorization: Bearer your_api_key" \
-F "document=@tracking_screenshot.png" \
-F "type=shipping_documentation"
```
### Evidence Types
| Type | Description |
| ------------------------ | ------------------------------------ |
| `receipt` | Purchase receipt or invoice |
| `shipping_documentation` | Tracking info, delivery confirmation |
| `communication` | Emails, chat logs with merchant |
| `cancellation_proof` | Cancellation confirmation |
| `refund_policy` | Merchant refund/return policy |
| `product_description` | Original product listing |
| `other` | Any other relevant documentation |
### View Submitted Evidence
```bash theme={"system"}
curl https://api.useproxy.ai/v1/disputes/dsp_xyz789/evidence \
-H "Authorization: Bearer your_api_key"
```
Response:
```json theme={"system"}
{
"textEvidence": "Order #12345 was placed on Jan 10...",
"documents": [
{
"id": "doc_001",
"type": "shipping_documentation",
"filename": "tracking_screenshot.png",
"uploadedAt": "2024-01-16T14:00:00Z"
}
]
}
```
## Dispute Resolution
### Checking Status
Disputes typically take 30-90 days to resolve. Check the status periodically:
```bash theme={"system"}
curl https://api.useproxy.ai/v1/disputes/dsp_xyz789 \
-H "Authorization: Bearer your_api_key"
```
### Resolution Outcomes
The dispute was decided in your favor. The provisional credit becomes permanent.
The dispute was decided against you. The provisional credit is reversed.
### Resolution Response
```json theme={"system"}
{
"id": "dsp_xyz789",
"status": "won",
"reason": "not_received",
"amount": 4500,
"creditAmount": 4500,
"resolution": {
"outcome": "won",
"resolvedAt": "2024-02-15T10:00:00Z",
"notes": "Merchant unable to provide delivery confirmation"
}
}
```
## Dispute Webhooks
Subscribe to dispute events for real-time notifications:
| Event | Description |
| ------------------ | ------------------------- |
| `dispute.created` | New dispute filed |
| `dispute.updated` | Dispute status changed |
| `dispute.resolved` | Dispute has been resolved |
### Webhook Payload
```json theme={"system"}
{
"id": "evt_abc123",
"type": "dispute.updated",
"createdAt": "2024-01-20T10:30:00Z",
"data": {
"disputeId": "dsp_xyz789",
"transactionId": "txn_abc123",
"previousStatus": "open",
"newStatus": "under_review",
"reason": "not_received"
}
}
```
## Dispute Timeframes
| Phase | Timeframe |
| ------------------- | ------------------------------- |
| Filing deadline | 60-120 days from transaction |
| Evidence submission | 7-20 days from dispute creation |
| Network review | 30-90 days |
| Second presentment | Up to 45 days (if applicable) |
Disputes must be filed within the network-specified timeframe (typically 60-120 days from the transaction date). Late disputes may be automatically rejected.
## Best Practices
File disputes promptly and submit evidence within the deadline.
Save all receipts, communications, and delivery confirmations.
Provide detailed descriptions with dates, amounts, and order numbers.
Submit screenshots, tracking info, and any supporting documents.
## Dispute Prevention
Reduce disputes with proper intent matching and transaction monitoring:
```json theme={"system"}
{
"policy": {
"requireIntent": true,
"requireAttestation": true,
"allowedMerchants": ["trusted-vendor.com"]
}
}
```
* Use `requireIntent` to ensure all transactions have documented purposes
* Enable `lockToFirstMerchant` for subscription cards
* Set appropriate spending limits with `perAuth` and `perDay`
* Monitor transactions via webhooks and flag suspicious activity
## Next Steps
View transaction history
Configure spending controls
Get real-time notifications
Manage card settings
# Intents
Source: https://docs.useproxy.ai/concepts/intents
Pre-transaction declarations of planned purchases
# Intents
An **Intent** is a pre-transaction declaration of what an agent plans to purchase. Intents enable policy enforcement before card details are accessed.
## Why Intents?
Intents serve several purposes:
1. **Approval workflows** - Require human approval for large purchases
2. **Merchant restrictions** - Validate purchases against allowed merchants
3. **Spending controls** - Enforce limits before transactions occur
4. **Audit trail** - Document the purpose of every transaction
## Creating an Intent
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/intents \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"purpose": "Purchase office supplies from Amazon",
"expectedAmount": 5000,
"expectedMerchant": "Amazon"
}'
```
## Intent Fields
| Field | Type | Description |
| ------------------ | ------ | ----------------------------------- |
| `purpose` | string | Human-readable description |
| `expectedAmount` | number | Expected transaction amount (cents) |
| `expectedMerchant` | string | Expected merchant name |
## Intent Lifecycle
| Status | Description |
| ------------------ | ------------------------------------- |
| `pending_approval` | Awaiting human approval |
| `pending` | Approved, awaiting transaction |
| `matched` | Transaction matched the intent |
| `mismatched` | Transaction didn't match expectations |
| `expired` | Intent expired before use |
## Matching Rules
When a transaction occurs, Proxy matches it against pending intents:
* **Amount tolerance**: ±10% of expected amount
* **Merchant matching**: Fuzzy match on merchant name
* **Time window**: Intent must not be expired
## Approval Workflows
If `requireApproval` is enabled in the policy, intents start in `pending_approval` status:
```bash theme={"system"}
# Approve an intent
curl -X POST https://api.useproxy.ai/v1/intents/int_xxx/approve \
-H "Authorization: Bearer your_api_key"
# Reject an intent
curl -X POST https://api.useproxy.ai/v1/intents/int_xxx/reject \
-H "Authorization: Bearer your_api_key"
```
## Next Steps
Learn about card controls
Get notified about intent status
# KYC
Source: https://docs.useproxy.ai/concepts/kyc
Know Your Customer verification for card issuance
# KYC
**KYC (Know Your Customer)** verification is required before customers can issue cards. Proxy handles identity verification through Rain's KYC infrastructure to comply with financial regulations.
## Why KYC?
Card issuance is a regulated activity. Before a customer can:
* Issue virtual cards
* Fund their account
* Make transactions
They must complete identity verification to prevent fraud and money laundering.
## Creating a KYC Application
Submit a KYC application with the customer's identity information:
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/kyc/applications \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cus_xxx",
"application": {
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-01-15",
"nationalId": "123456789",
"countryOfIssue": "US",
"email": "john@example.com",
"address": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94102",
"country": "US"
},
"ipAddress": "1.2.3.4",
"occupation": "SOFTWARE_ENGINEER",
"annualSalary": "100000_149999",
"accountPurpose": "PERSONAL_SPENDING",
"expectedMonthlyVolume": "1000_4999",
"isTermsOfServiceAccepted": true,
"phoneCountryCode": "1",
"phoneNumber": "5551234567"
}
}'
```
### Required Fields
| Field | Type | Description |
| -------------------------- | ------- | ------------------------------------------ |
| `firstName` | string | Customer's first name (max 50 chars) |
| `lastName` | string | Customer's last name (max 50 chars) |
| `birthDate` | string | Date of birth in `YYYY-MM-DD` format |
| `nationalId` | string | National ID (9-digit SSN for US customers) |
| `countryOfIssue` | string | 2-letter country code for national ID |
| `email` | string | Customer's email address |
| `address` | object | Customer's physical address |
| `ipAddress` | string | Customer's IP address |
| `occupation` | string | Customer's occupation code |
| `annualSalary` | string | Annual salary range |
| `accountPurpose` | string | Purpose of account |
| `expectedMonthlyVolume` | string | Expected monthly spend range |
| `isTermsOfServiceAccepted` | boolean | Must be `true` |
| `phoneCountryCode` | string | Phone country code (e.g., "1" for US) |
| `phoneNumber` | string | Phone number without country code |
### Address Object
| Field | Type | Description |
| ------------ | ------ | --------------------------------- |
| `line1` | string | Street address |
| `line2` | string | Apartment, suite, etc. (optional) |
| `city` | string | City |
| `state` | string | State/province code |
| `postalCode` | string | Postal/ZIP code |
| `country` | string | 2-letter country code |
### Optional Fields
| Field | Type | Description |
| --------------- | ------ | ---------------------------------------------------- |
| `walletAddress` | string | EVM wallet address (auto-created if not provided) |
| `solanaAddress` | string | Solana wallet address (auto-created if not provided) |
You don't need to provide a wallet address. Proxy automatically creates a secure server-managed wallet for each customer during KYC.
### Occupation Codes
Common values:
* `SOFTWARE_ENGINEER`
* `PRODUCT_MANAGER`
* `BUSINESS_OWNER`
* `ACCOUNTANT`
* `CONSULTANT`
* `OTHER`
### Salary Ranges
* `0_24999`
* `25000_49999`
* `50000_99999`
* `100000_149999`
* `150000_249999`
* `250000_499999`
* `500000_PLUS`
### Monthly Volume Ranges
* `0_999`
* `1000_4999`
* `5000_9999`
* `10000_24999`
* `25000_49999`
* `50000_PLUS`
### Account Purpose
* `PERSONAL_SPENDING`
* `BUSINESS_EXPENSES`
* `PAYROLL`
* `VENDOR_PAYMENTS`
## Response
```json theme={"system"}
{
"id": "app_xxx",
"customerId": "cus_xxx",
"status": "pending",
"reason": null,
"completionLink": "https://verify.example.com/complete/xyz789"
}
```
| Field | Description |
| ---------------- | ---------------------------------------------------- |
| `id` | Application ID |
| `customerId` | Your customer ID |
| `status` | Current application status |
| `reason` | Reason if status is not `approved` |
| `completionLink` | URL for customer to complete additional verification |
## Application Statuses
| Status | Description |
| ------------------- | ---------------------------------------------------------------- |
| `pending` | Application submitted, under review |
| `approved` | Verified, customer can issue cards |
| `needsInformation` | Additional info required |
| `needsVerification` | Identity verification needed - send customer to `completionLink` |
| `manualReview` | Flagged for manual review |
| `denied` | Application rejected |
| `locked` | Account locked |
## KYC Flow
Create a customer record via `POST /v1/customers`
Submit application with all required identity fields
Response indicates if additional verification is needed
If `needsVerification`, direct customer to `completionLink` to upload ID documents
Poll status or receive webhook when application is approved
Once `approved`, customer can issue virtual cards
## Checking Application Status
```bash theme={"system"}
curl https://api.useproxy.ai/v1/kyc/applications/app_xxx \
-H "Authorization: Bearer sk_live_xxx"
```
Response:
```json theme={"system"}
{
"id": "app_xxx",
"customerId": "cus_xxx",
"status": "needsVerification",
"reason": "Identity verification required",
"completionLink": "https://verify.example.com/complete/xyz789"
}
```
## Completion Link
When status is `needsInformation` or `needsVerification`, the response includes a `completionLink`. Direct your customer to this URL to complete the verification process (e.g., upload government ID).
Completion links expire after 24 hours. Request a new application status to get a fresh link if needed.
## Webhooks
Subscribe to KYC events for real-time updates:
| Event | Description |
| -------------- | ----------------------------------- |
| `kyc.approved` | Customer approved for card issuance |
| `kyc.rejected` | Application was rejected |
## Next Steps
Learn about customer management
Issue cards after KYC approval
# Policies
Source: https://docs.useproxy.ai/concepts/policies
Spending controls and approval rules for cards and agents
# Policies
**Policies** define the rules governing how cards can be used. They control spending limits, merchant restrictions, approval workflows, and more.
## Policy Cascade
Policies are applied in a cascading hierarchy. Settings at lower levels override those at higher levels:
```
Customer Policy → Agent Policy → Card Policy
```
Default policies for all agents and cards owned by the customer.
```json theme={"system"}
{
"policy": {
"requireIntent": true,
"autoApproveBelow": 10000,
"limits": {
"perDay": 100000
}
}
}
```
Overrides customer defaults for a specific agent and its cards.
```json theme={"system"}
{
"policy": {
"requireApproval": true,
"limits": {
"perAuth": 5000,
"perDay": 25000
}
}
}
```
Most specific; overrides both customer and agent policies.
```json theme={"system"}
{
"policy": {
"allowedMerchants": ["amazon.com"],
"lockToFirstMerchant": true,
"limits": {
"perAuth": 2500
}
}
}
```
### Cascade Example
| Setting | Customer | Agent | Card | Effective |
| --------------------- | -------- | ------- | ------ | --------- |
| `requireIntent` | `true` | - | - | `true` |
| `perAuth` limit | `10000` | `5000` | `2500` | `2500` |
| `perDay` limit | `100000` | `25000` | - | `25000` |
| `lockToFirstMerchant` | - | - | `true` | `true` |
## Intent Controls
### requireIntent
When `true`, agents must declare an intent before accessing card details. Transactions without a matching intent are flagged.
```json theme={"system"}
{
"policy": {
"requireIntent": true
}
}
```
**Use case**: Audit trail and compliance. Ensures every transaction has a documented purpose.
### requireAttestation
When `true`, agents must attest to their intent before each card access. Creates an access event record.
```json theme={"system"}
{
"policy": {
"requireAttestation": true,
"attestationWindowMinutes": 15
}
}
```
| Field | Type | Description |
| -------------------------- | ------- | -------------------------------------- |
| `requireAttestation` | boolean | Require attestation before card access |
| `attestationWindowMinutes` | number | Minutes the attestation is valid |
### requireApproval
When `true`, intents require human approval before becoming active.
```json theme={"system"}
{
"policy": {
"requireApproval": true,
"autoApproveBelow": 5000
}
}
```
| Field | Type | Description |
| ------------------ | ------- | ---------------------------------------------- |
| `requireApproval` | boolean | Intents need approval |
| `autoApproveBelow` | number | Auto-approve intents under this amount (cents) |
**Flow with approval required:**
```
Intent Created → pending_approval → [Human Approves] → pending → Transaction → matched
```
## Spending Limits
Control maximum spend amounts at different time intervals.
```json theme={"system"}
{
"policy": {
"limits": {
"perAuth": 5000,
"perDay": 50000,
"perMonth": 200000
}
}
}
```
| Limit | Description |
| ---------- | ---------------------------------------------- |
| `perAuth` | Maximum amount per single transaction (cents) |
| `perDay` | Maximum total spend per 24-hour period (cents) |
| `perMonth` | Maximum total spend per calendar month (cents) |
### Limit Enforcement
Limits are checked at authorization time. If a transaction would exceed any limit, it is declined.
```bash Example: $50 limit per transaction theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"agentId": "agent_xxx",
"policy": {
"limits": {
"perAuth": 5000
}
}
}'
```
```bash Example: $500/day limit theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"agentId": "agent_xxx",
"policy": {
"limits": {
"perDay": 50000
}
}
}'
```
## MCC Restrictions
Merchant Category Codes (MCCs) classify the type of business. Use MCC restrictions to control where cards can be used.
### allowedMccs
Whitelist specific merchant categories. Only transactions at merchants with these MCCs are allowed.
```json theme={"system"}
{
"policy": {
"allowedMccs": ["5411", "5412", "5499"]
}
}
```
| MCC | Category |
| ---- | ---------------------------- |
| 5411 | Grocery Stores, Supermarkets |
| 5412 | Grocery Stores |
| 5499 | Misc. Food Stores |
| 5812 | Eating Places, Restaurants |
| 5942 | Book Stores |
### blockedMccs
Blacklist specific merchant categories. Transactions at these MCCs are declined.
```json theme={"system"}
{
"policy": {
"blockedMccs": ["7995", "6211", "5933"]
}
}
```
| MCC | Category |
| ---- | ------------------------ |
| 7995 | Betting, Casino Gambling |
| 6211 | Securities/Brokers |
| 5933 | Pawn Shops |
| 5993 | Cigar Stores, Tobacco |
If both `allowedMccs` and `blockedMccs` are specified, `allowedMccs` takes precedence. A transaction is allowed only if the MCC is in the allowed list and not in the blocked list.
## Merchant Controls
### allowedMerchants
Whitelist specific merchants by name. Only transactions at these merchants are allowed.
```json theme={"system"}
{
"policy": {
"allowedMerchants": ["amazon.com", "walmart.com", "target.com"]
}
}
```
Merchant matching uses fuzzy matching to handle variations in merchant names.
### lockToFirstMerchant
After the first transaction, lock the card to that specific merchant. All subsequent transactions must be at the same merchant.
```json theme={"system"}
{
"policy": {
"lockToFirstMerchant": true
}
}
```
**Use case**: Subscription payments. Issue a card for a specific service and prevent misuse at other merchants.
## Cooldown Periods
Prevent rapid consecutive transactions by enforcing a wait period between card uses.
```json theme={"system"}
{
"policy": {
"cooldownMinutes": 30
}
}
```
| Field | Type | Description |
| ----------------- | ------ | ------------------------------------ |
| `cooldownMinutes` | number | Minimum minutes between transactions |
**Use case**: Prevent runaway spending by AI agents. If an agent makes a purchase, it must wait before making another.
## Card Expiration
Control how long cards remain active.
```json theme={"system"}
{
"policy": {
"ttlMinutes": 60,
"ttlDays": 7
}
}
```
| Field | Type | Description |
| ------------ | ------ | ---------------------------- |
| `ttlMinutes` | number | Card expires after N minutes |
| `ttlDays` | number | Card expires after N days |
## Example Configurations
Minimal restrictions for a trusted automation.
```json theme={"system"}
{
"policy": {
"requireIntent": false,
"limits": {
"perAuth": 100000,
"perDay": 500000
}
}
}
```
Requires approval for significant purchases.
```json theme={"system"}
{
"policy": {
"requireIntent": true,
"requireApproval": true,
"autoApproveBelow": 2500,
"limits": {
"perAuth": 25000,
"perDay": 100000
},
"cooldownMinutes": 15
}
}
```
Locked to specific merchant category with tight limits.
```json theme={"system"}
{
"policy": {
"requireIntent": true,
"requireAttestation": true,
"attestationWindowMinutes": 10,
"allowedMccs": ["5812"],
"limits": {
"perAuth": 5000,
"perDay": 10000
},
"lockToFirstMerchant": true
}
}
```
For recurring payments at a single merchant.
```json theme={"system"}
{
"policy": {
"lockToFirstMerchant": true,
"limits": {
"perAuth": 10000,
"perMonth": 10000
}
}
}
```
## Setting Policies
### On Customer Creation
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/customers \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"type": "consumer",
"email": "alice@example.com",
"name": { "first": "Alice", "last": "Smith" },
"policy": {
"requireIntent": true,
"limits": {
"perDay": 100000
}
}
}'
```
### On Agent Creation
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/agents \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"name": "Shopping Agent",
"policy": {
"requireApproval": true,
"autoApproveBelow": 5000,
"blockedMccs": ["7995"]
}
}'
```
### On Card Creation
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"agentId": "agent_xxx",
"policy": {
"allowedMerchants": ["amazon.com"],
"limits": {
"perAuth": 2500
}
}
}'
```
### Updating Policies
```bash theme={"system"}
curl -X PATCH https://api.useproxy.ai/v1/agents/agent_xxx \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"policy": {
"limits": {
"perAuth": 7500
}
}
}'
```
## Policy Reference
| Field | Type | Default | Description |
| -------------------------- | ------- | ------- | ---------------------------------------------- |
| `requireIntent` | boolean | `false` | Require intent before card access |
| `requireAttestation` | boolean | `false` | Require attestation before card access |
| `requireApproval` | boolean | `false` | Require human approval for intents |
| `autoApproveBelow` | number | - | Auto-approve intents under this amount (cents) |
| `attestationWindowMinutes` | number | `15` | Minutes attestation remains valid |
| `cooldownMinutes` | number | - | Minimum minutes between transactions |
| `ttlMinutes` | number | - | Card expires after N minutes |
| `ttlDays` | number | - | Card expires after N days |
| `limits.perAuth` | number | - | Max per-transaction amount (cents) |
| `limits.perDay` | number | - | Max daily spend (cents) |
| `limits.perMonth` | number | - | Max monthly spend (cents) |
| `allowedMccs` | array | - | Whitelist of allowed MCCs |
| `blockedMccs` | array | - | Blacklist of blocked MCCs |
| `allowedMerchants` | array | - | Whitelist of allowed merchant names |
| `lockToFirstMerchant` | boolean | `false` | Lock card to first merchant |
## Next Steps
Configure agent policies
Apply card-level controls
Understand intent workflows
View transaction history
# Transactions
Source: https://docs.useproxy.ai/concepts/transactions
Card spend events from authorization through settlement
# Transactions
A **Transaction** represents a card spend event on the payment network. Transactions flow through multiple stages from initial authorization to final settlement.
## Transaction Lifecycle
When a card is used at a merchant, the payment network sends an authorization request. Proxy evaluates the request against policies and available funds.
```
Card Used → Authorization Request → Policy Check → Approve/Decline
```
* **Approved**: A hold is placed on funds equal to the authorized amount
* **Declined**: No hold is placed; transaction is rejected
After authorization, the merchant settles the transaction (typically 1-3 days later). The held funds are released and the final amount is posted.
```
Authorization Hold → Merchant Settlement → Hold Released → Amount Posted
```
Settlement amounts may differ from authorization (e.g., tips, fuel purchases).
* **Partial capture**: Merchant settles less than authorized
* **Over-capture**: Merchant settles more (allowed for specific MCCs like restaurants)
* **Force capture**: Settlement without prior authorization (offline transactions)
* **Refunds**: Negative settlement amounts credited to the balance
## Transaction Types
| Type | Description |
| --------------- | ----------------------------------------- |
| `authorization` | Initial approval request from merchant |
| `settlement` | Final capture of authorized amount |
| `refund` | Credit returned to cardholder |
| `reversal` | Authorization cancelled before settlement |
| `force_capture` | Settlement without prior authorization |
## Transaction Statuses
| Status | Description |
| ---------- | ------------------------------------------- |
| `pending` | Authorization approved, awaiting settlement |
| `settled` | Transaction completed and posted |
| `declined` | Authorization was rejected |
| `reversed` | Authorization cancelled; hold released |
## Transaction Fields
| Field | Type | Description |
| ------------ | ------ | --------------------------------- |
| `id` | string | Unique transaction identifier |
| `cardId` | string | Card used for transaction |
| `customerId` | string | Owner of the card |
| `agentId` | string | Agent that initiated the spend |
| `intentId` | string | Matched intent (if any) |
| `amount` | number | Transaction amount in cents |
| `currency` | string | Currency code (e.g., `USD`) |
| `status` | string | Current transaction status |
| `type` | string | Transaction type |
| `merchant` | object | Merchant details |
| `createdAt` | string | Timestamp of transaction creation |
### Merchant Object
| Field | Type | Description |
| ---------- | ------ | ----------------------- |
| `name` | string | Merchant name |
| `mcc` | string | Merchant Category Code |
| `city` | string | Merchant city |
| `country` | string | Merchant country code |
| `category` | string | Human-readable category |
## Intent Matching
When a transaction occurs, Proxy automatically matches it against pending intents for the card.
### Matching Rules
Transaction amount must be within the configured tolerance of the expected amount (default: +/- 10%)
Fuzzy matching on merchant name if `expectedMerchant` was specified
MCC must be in `expectedMccs` list if specified
Transaction must occur before intent expiration
### Match Outcomes
| Status | Description |
| ------------ | -------------------------------------------------- |
| `matched` | Transaction matched all intent criteria |
| `mismatched` | Transaction occurred but didn't match expectations |
| `expired` | Intent expired before any transaction |
## Viewing Transactions
### List Transactions
```bash theme={"system"}
curl https://api.useproxy.ai/v1/transactions \
-H "Authorization: Bearer your_api_key"
```
Response:
```json theme={"system"}
{
"transactions": [
{
"id": "txn_abc123",
"cardId": "card_xyz789",
"amount": 4250,
"currency": "USD",
"status": "settled",
"type": "settlement",
"merchant": {
"name": "AMAZON.COM",
"mcc": "5942",
"city": "SEATTLE",
"country": "US",
"category": "Book Stores"
},
"intentId": "int_def456",
"intentStatus": "matched",
"createdAt": "2024-01-15T10:30:00Z"
}
],
"cursor": "next_page_token"
}
```
### Filter by Card
```bash theme={"system"}
curl "https://api.useproxy.ai/v1/transactions?cardId=card_xyz789" \
-H "Authorization: Bearer your_api_key"
```
### Filter by Status
```bash theme={"system"}
curl "https://api.useproxy.ai/v1/transactions?status=pending" \
-H "Authorization: Bearer your_api_key"
```
### Filter by Date Range
```bash theme={"system"}
curl "https://api.useproxy.ai/v1/transactions?startDate=2024-01-01&endDate=2024-01-31" \
-H "Authorization: Bearer your_api_key"
```
### Get Single Transaction
```bash theme={"system"}
curl https://api.useproxy.ai/v1/transactions/txn_abc123 \
-H "Authorization: Bearer your_api_key"
```
## Transaction Webhooks
Subscribe to transaction events for real-time notifications:
| Event | Description |
| ---------------------- | ----------------------------------------------------------- |
| `transaction.created` | New authorization approved or declined |
| `transaction.updated` | Authorization modified (incremental auth, partial reversal) |
| `transaction.settled` | Transaction settled and posted |
| `transaction.declined` | Authorization was declined |
### Webhook Payload
```json theme={"system"}
{
"id": "evt_abc123",
"type": "transaction.created",
"createdAt": "2024-01-15T10:30:00Z",
"data": {
"transactionId": "txn_xyz789",
"cardId": "card_abc123",
"amount": 4250,
"currency": "USD",
"status": "pending",
"type": "authorization",
"merchant": {
"name": "AMAZON.COM",
"mcc": "5942"
}
}
}
```
## Decline Reasons
When a transaction is declined, the response includes a reason:
| Reason | Description |
| ------------------------------ | ---------------------------------------- |
| `insufficient_funds` | Not enough available balance |
| `card_spending_limit_exceeded` | Exceeds card limit |
| `blocked_merchant` | Merchant is blocked |
| `blocked_mcc` | MCC is restricted |
| `card_frozen` | Card is temporarily frozen |
| `card_canceled` | Card has been closed |
| `policy_violation` | Transaction violates policy rules |
| `no_valid_intent` | No matching intent found (when required) |
## Adding a Memo
Attach a note to a transaction for record-keeping:
```bash theme={"system"}
curl -X PATCH https://api.useproxy.ai/v1/transactions/txn_abc123 \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"memo": "Office supplies for Q1 project"
}'
```
## Uploading Receipts
Attach a receipt to a transaction:
```bash theme={"system"}
curl -X PUT https://api.useproxy.ai/v1/transactions/txn_abc123/receipt \
-H "Authorization: Bearer your_api_key" \
-F "receipt=@receipt.pdf"
```
Retrieve a receipt:
```bash theme={"system"}
curl https://api.useproxy.ai/v1/transactions/txn_abc123/receipt \
-H "Authorization: Bearer your_api_key" \
-o receipt.pdf
```
## Next Steps
Declare purchase intents
Handle transaction disputes
Understand fund management
Get real-time notifications
# Webhooks
Source: https://docs.useproxy.ai/concepts/webhooks
Real-time event notifications
# Webhooks
Webhooks provide real-time notifications when events occur in your Proxy account. Configure endpoints to receive HTTP POST requests for events you care about.
## Setting Up Webhooks
### Create a Webhook Endpoint
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/webhooks \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/proxy",
"events": ["transaction.created", "intent.matched"],
"description": "Production webhook"
}'
```
### Webhook Fields
| Field | Type | Description |
| ------------- | ------ | ----------------------------------- |
| `url` | string | HTTPS endpoint to receive events |
| `events` | array | List of event types to subscribe to |
| `description` | string | Human-readable description |
| `status` | string | `active` or `disabled` |
## Event Types
### Transaction Events
| Event | Description |
| ---------------------- | ------------------------ |
| `transaction.created` | New transaction recorded |
| `transaction.settled` | Transaction settled |
| `transaction.declined` | Transaction was declined |
### Intent Events
| Event | Description |
| ------------------------- | ------------------------------- |
| `intent.created` | New intent declared |
| `intent.matched` | Intent matched to transaction |
| `intent.mismatched` | Transaction didn't match intent |
| `intent.expired` | Intent expired |
| `intent.pending_approval` | Intent awaiting approval |
### Card Events
| Event | Description |
| -------------- | --------------- |
| `card.created` | New card issued |
| `card.frozen` | Card was frozen |
| `card.closed` | Card was closed |
## Webhook Payload
```json theme={"system"}
{
"id": "evt_xxx",
"type": "transaction.created",
"createdAt": "2024-01-15T10:30:00Z",
"data": {
"transactionId": "txn_xxx",
"cardId": "card_xxx",
"amount": 5000,
"merchant": "Amazon"
}
}
```
## Signature Verification
All webhooks include a `Proxy-Signature` header for verification. The header format is:
```
Proxy-Signature: t=1706745600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```
Where:
* `t` is the Unix timestamp (seconds) when the webhook was sent
* `v1` is the HMAC-SHA256 signature
The signature is computed over `{timestamp}.{json_payload}` using your webhook secret.
### Node.js Example
```javascript theme={"system"}
const crypto = require('crypto');
function verifyWebhook(req, secret) {
const signature = req.headers['proxy-signature'];
const payload = JSON.stringify(req.body);
// Parse the signature header
const parts = signature.split(',');
const timestamp = parts[0].split('=')[1];
const receivedSig = parts[1].split('=')[1];
// Compute expected signature
const signedPayload = `${timestamp}.${payload}`;
const expectedSig = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
// Compare signatures (use timing-safe comparison)
return crypto.timingSafeEqual(
Buffer.from(receivedSig),
Buffer.from(expectedSig)
);
}
// Express.js handler example
app.post('/webhooks/proxy', express.json(), (req, res) => {
const secret = 'whsec_your_webhook_secret';
if (!verifyWebhook(req, secret)) {
return res.status(401).send('Invalid signature');
}
// Process the webhook
const event = req.body;
console.log('Received event:', event.type);
res.status(200).send('OK');
});
```
### Convex Example
```typescript theme={"system"}
import { httpAction } from "./_generated/server";
export const webhookHandler = httpAction(async (ctx, request) => {
const signature = request.headers.get("proxy-signature");
const body = await request.text();
const secret = process.env.PROXY_WEBHOOK_SECRET!;
// Parse signature
const parts = signature?.split(',') || [];
const timestamp = parts[0]?.split('=')[1];
const receivedSig = parts[1]?.split('=')[1];
// Verify signature
const signedPayload = `${timestamp}.${body}`;
const encoder = new TextEncoder();
const key = await crypto.subtle.importKey(
"raw",
encoder.encode(secret),
{ name: "HMAC", hash: "SHA-256" },
false,
["sign"]
);
const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(signedPayload));
const expectedSig = Array.from(new Uint8Array(sig))
.map(b => b.toString(16).padStart(2, '0'))
.join('');
if (receivedSig !== expectedSig) {
return new Response("Invalid signature", { status: 401 });
}
// Process webhook
const event = JSON.parse(body);
console.log("Received:", event.type);
return new Response("OK", { status: 200 });
});
```
Always verify webhook signatures before processing events. This ensures the request came from Proxy and hasn't been tampered with.
## Retry Policy
Failed webhook deliveries are retried with exponential backoff:
| Attempt | Delay |
| ------- | ---------- |
| 1 | Immediate |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 24 hours |
After 5 failed attempts, the webhook is marked as failed and requires manual retry.
## Managing Webhooks
### List Webhooks
```bash theme={"system"}
curl https://api.useproxy.ai/v1/webhooks \
-H "Authorization: Bearer your_api_key"
```
### Update a Webhook
```bash theme={"system"}
curl -X PATCH https://api.useproxy.ai/v1/webhooks/wh_xxx \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"events": ["transaction.created", "transaction.declined"]
}'
```
### Delete a Webhook
```bash theme={"system"}
curl -X DELETE https://api.useproxy.ai/v1/webhooks/wh_xxx \
-H "Authorization: Bearer your_api_key"
```
## Next Steps
Full API documentation
Get started quickly
# Introduction
Source: https://docs.useproxy.ai/introduction
Virtual cards for AI agents
# Proxy
Proxy issues virtual cards for AI agents with policy-based spending controls.
Issue your first card in minutes
Explore the API
## How It Works
Register the entity who will fund card spending.
Create an autonomous actor that spends on behalf of the customer.
Create a virtual card with spending policies and limits.
Before spending, the agent declares what it plans to purchase.
The agent retrieves card credentials and completes the purchase.
## Core Concepts
| Concept | Description |
| ------------ | ---------------------------------------------------- |
| **Customer** | Entity who owns funds and cards |
| **Agent** | AI or automation that spends on behalf of a customer |
| **Card** | Virtual spending instrument with policy controls |
| **Intent** | Pre-transaction declaration of planned purchase |
## Next Steps
Learn about customers
Learn about agents
Learn about cards
Real-time notifications
# MCP Overview
Source: https://docs.useproxy.ai/mcp/introduction
Enable AI agents to manage Proxy cards through the Model Context Protocol
# Model Context Protocol (MCP)
The Proxy MCP server enables AI assistants like Claude, Cursor, and other MCP-compatible tools to interact with your Proxy account directly through natural conversation.
## What is MCP?
The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard developed by Anthropic that allows AI models to securely connect to external data sources and tools. Instead of copying API documentation and writing code, you can simply ask your AI assistant to perform actions.
## Why Use MCP with Proxy?
Ask "Create a card for my shopping agent" instead of writing API calls
The AI understands your account state and can chain operations intelligently
OAuth 2.0 authentication ensures your credentials stay safe
Manage cards, agents, and transactions directly from your IDE or chat interface
## Example Interactions
Once configured, you can have conversations like:
```
You: Create a new agent called "Research Assistant" with a $500 monthly limit
Claude: I've created the agent "Research Assistant" with ID agent_abc123.
It has a spending limit of $500/month. Would you like me to create
a card for this agent?
You: Yes, create a virtual card for it
Claude: Done! Card created (ending in 4242). The agent can now use this
card for purchases. Should I configure any spending policies?
```
## Available Operations
The Proxy MCP server exposes 29 tools across these categories:
| Category | Description |
| ---------------- | ---------------------------------------------- |
| **Onboarding** | Start onboarding, check status |
| **KYC** | Get verification links, check KYC status |
| **Agents** | Create, list, update, pause, disable agents |
| **Cards** | Create, list, lock, unlock, cancel cards |
| **Intents** | Declare spending intents (agent-only) |
| **Access** | Request card credentials (agent-only) |
| **Transactions** | View transaction history |
| **Disputes** | File and manage disputes |
| **Funding** | Get deposit instructions, view funding history |
| **Balance** | Check available balance |
## Authentication Types
The MCP server supports two authentication modes:
### User Authentication
Authenticated via Clerk JWT tokens. Users can:
* Manage agents and cards
* Configure policies
* View all transactions
* Handle disputes and funding
### Agent Authentication
Authenticated via agent tokens (`agt_xxx`). Agents can:
* Create spending intents
* Request card access (retrieve credentials)
* View their own cards and transactions
* Check balance
## Architecture
```
+----------------+ +------------------+ +----------------+
| Claude/Cursor | --> | Proxy MCP | --> | Proxy API |
| (MCP Client) | | Server | | (Convex) |
+----------------+ +------------------+ +----------------+
| |
| JSON-RPC 2.0 | Authenticated
| over HTTP | mutations/queries
```
The MCP server acts as a bridge between AI assistants and the Proxy platform, translating natural language requests into authenticated API calls.
## Next Steps
Set up the MCP server in your IDE
Complete tool documentation
# MCP Quickstart
Source: https://docs.useproxy.ai/mcp/quickstart
Set up the Proxy MCP server with Claude, Cursor, and other AI tools
# MCP Quickstart
This guide walks you through connecting the Proxy MCP server to your preferred AI assistant.
## Prerequisites
* A Proxy account with completed KYC ([sign up](https://dashboard.useproxy.ai))
* An AI assistant that supports MCP (Claude Desktop, Cursor, etc.)
## Server URL
The Proxy MCP server is hosted at:
```
https://mcp.useproxy.ai/api/mcp
```
## Authentication
The MCP server uses OAuth 2.0 for authentication. You'll need to authorize the connection through your Proxy account.
The OAuth flow will redirect you to Proxy's authentication page. After signing in, the connection will be established automatically.
## Setup by Platform
### Claude Desktop Setup
1. Open Claude Desktop settings
2. Navigate to **Developer** > **Model Context Protocol**
3. Click **Add Server**
4. Configure the server:
```json theme={"system"}
{
"mcpServers": {
"proxy": {
"url": "https://mcp.useproxy.ai/api/mcp",
"transport": "streamable-http"
}
}
}
```
5. Click **Save** and restart Claude Desktop
6. When prompted, authorize the connection through Proxy
### Verify Connection
Ask Claude: "What tools do you have from Proxy?"
Claude should list the available Proxy tools including `agent.create`, `card.list`, etc.
### Cursor Setup
1. Open Cursor Settings (`Cmd/Ctrl + ,`)
2. Navigate to **Features** > **MCP Servers**
3. Click **Add new MCP server**
4. Enter the configuration:
**Name:** `proxy`
**URL:** `https://mcp.useproxy.ai/api/mcp`
**Transport:** `streamable-http`
5. Save and authorize when prompted
### Using in Cursor
In the Composer or Chat, you can now ask Cursor to interact with Proxy:
```
Create a new agent called "Code Assistant" for handling software purchases
```
### Custom MCP Client
If you're building a custom MCP client, connect using these parameters:
**Endpoint:** `https://mcp.useproxy.ai/api/mcp`
**Transport:** HTTP with Server-Sent Events (SSE)
**Authentication:** OAuth 2.0 Bearer token
#### OAuth Configuration
Discover OAuth metadata at:
```
https://mcp.useproxy.ai/.well-known/oauth-protected-resource
```
#### Example Connection (Node.js)
```javascript theme={"system"}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@anthropic-ai/mcp-client";
const transport = new StreamableHTTPClientTransport({
url: "https://mcp.useproxy.ai/api/mcp",
headers: {
Authorization: `Bearer ${accessToken}`,
},
});
const client = new Client({
name: "my-app",
version: "1.0.0",
});
await client.connect(transport);
// List available tools
const tools = await client.listTools();
console.log(tools);
// Call a tool
const result = await client.callTool("agent.list", {});
console.log(result);
```
#### JSON-RPC Protocol
The server uses JSON-RPC 2.0. Direct HTTP calls:
```bash theme={"system"}
# List tools
curl -X POST https://mcp.useproxy.ai/api/mcp \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'
# Call a tool
curl -X POST https://mcp.useproxy.ai/api/mcp \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "agent.list",
"arguments": {}
}
}'
```
## First Steps
Once connected, try these example commands:
### Check Your Account Status
```
What's my onboarding status?
```
### Create an Agent
```
Create an agent called "Shopping Assistant" for handling e-commerce purchases
```
### Issue a Card
```
Create a virtual card for my Shopping Assistant agent with a $200 daily limit
```
### Check Balance
```
What's my current balance?
```
## Agent Authentication
For autonomous agent workflows, you can authenticate using an agent token instead of user OAuth.
### Generate an Agent Token
1. In your AI assistant, ask:
```
Create a token for my Shopping Assistant agent
```
2. Save the returned token securely (it won't be shown again)
### Use Agent Token
Agent tokens can be used directly in the Authorization header:
```bash theme={"system"}
curl -X POST https://mcp.useproxy.ai/api/mcp \
-H "Authorization: Bearer agt_xxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "intent.create",
"arguments": {
"cardId": "card_xxx",
"summary": "Purchase development tools",
"expectedAmount": 9900
}
}
}'
```
Agent tokens have limited permissions. They can only access intent, access, card (read-only), transaction (read-only), and balance tools.
## Troubleshooting
* Verify the server URL is correct: `https://mcp.useproxy.ai/api/mcp`
* Check that your network allows outbound HTTPS connections
* Try the health endpoint: `curl https://mcp.useproxy.ai/api/mcp/health`
* Ensure you completed the OAuth flow
* Try disconnecting and reconnecting the MCP server
* Check that your Proxy account is active
* Verify the tool name matches exactly (e.g., `agent.create` not `createAgent`)
* Ensure you're using the correct authentication type (some tools require user auth, others agent auth)
* Check that you own the resource you're trying to access
* Agent tokens can only access their own cards and intents
* Some operations require user authentication (not agent tokens)
## Next Steps
Complete documentation of all 29 MCP tools
Learn about agent architecture
# MCP Tools Reference
Source: https://docs.useproxy.ai/mcp/tools
Complete documentation for all Proxy MCP tools
# MCP Tools Reference
The Proxy MCP server provides 29 tools organized into logical categories. Each tool has specific authentication requirements and parameters.
## Authentication Requirements
Tools are restricted based on authentication type:
| Auth Type | Description |
| --------- | ------------------------------------- |
| **User** | Requires Clerk JWT token (OAuth flow) |
| **Agent** | Requires agent token (`agt_xxx`) |
| **Both** | Accessible by either user or agent |
***
## Onboarding
Tools for initializing customer accounts.
### onboarding.start
Create or link a customer account and return KYC status.
Customer email address
Customer first name
Customer last name
Customer type: `consumer` or `corporate`
**Auth:** User only
**Response:**
```json theme={"system"}
{
"customerId": "cust_abc123",
"status": "created",
"kycStatus": "not_started",
"completionLink": null
}
```
***
### onboarding.status
Fetch the current onboarding and KYC status.
**Auth:** User only
**Parameters:** None
**Response:**
```json theme={"system"}
{
"customerId": "cust_abc123",
"type": "consumer",
"status": "approved",
"kycStatus": "verified",
"completionLink": null,
"rainUserId": "usr_xxx"
}
```
***
## KYC
Tools for identity verification.
### kyc.link
Return a hosted KYC verification link for the current user.
**Auth:** User only
**Parameters:** None
**Response:**
```json theme={"system"}
{
"url": "https://verify.raincards.xyz/...",
"status": "initiated",
"message": "Complete verification at the provided URL."
}
```
***
### kyc.status
Return the current KYC verification status.
**Auth:** User only
**Parameters:** None
**Response:**
```json theme={"system"}
{
"status": "approved",
"reason": null,
"kycVerified": true
}
```
***
## Agents
Tools for managing autonomous agents.
### agent.create
Create a new agent for the customer.
Human-readable agent name
Your unique identifier for the agent
Initial status: `active`, `paused`, or `disabled`
Spending limit amount (in cents)
Spending limit currency (default: `usd`)
Policy overrides (see [Cards](/concepts/cards) for policy options)
Custom metadata key-value pairs
**Auth:** User only
**Response:**
```json theme={"system"}
{
"agentId": "agent_abc123",
"name": "Shopping Assistant",
"status": "active",
"externalId": "my-agent-001"
}
```
***
### agent.list
List all agents for the customer.
Maximum results to return (default: 50)
**Auth:** User only
**Response:**
```json theme={"system"}
{
"agents": [
{
"agentId": "agent_abc123",
"name": "Shopping Assistant",
"status": "active",
"externalId": "my-agent-001",
"createdAt": 1706745600000
}
],
"hasMore": false
}
```
***
### agent.update
Update agent metadata, limits, or policy.
Agent public ID
New agent name
New external identifier
New spending limit amount
New spending limit currency
Policy overrides
Custom metadata
**Auth:** User only
***
### agent.pause
Temporarily pause an agent. Paused agents cannot access cards or make purchases.
Agent public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"agentId": "agent_abc123",
"status": "paused"
}
```
***
### agent.disable
Permanently disable an agent. Disabled agents cannot be reactivated.
Agent public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"agentId": "agent_abc123",
"status": "disabled"
}
```
***
### agent.token.issue
Create a new authentication token for an agent.
Agent public ID
Token name for identification
**Auth:** User only
**Response:**
```json theme={"system"}
{
"tokenId": "tok_abc123",
"token": "agt_xxxxxxxxxxxxxxxxxxxx",
"warning": "Store this token securely. It will not be shown again."
}
```
The token value is only returned once. Store it securely immediately after creation.
***
### agent.token.revoke
Revoke an agent token, immediately invalidating it.
Token public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"tokenId": "tok_abc123",
"revoked": true
}
```
***
## Cards
Tools for managing virtual cards.
### card.create
Create a new virtual card. Requires completed KYC verification.
Agent to assign the card to
Card display name (default: "Virtual Card")
Card usage type: `single` (one-time) or `multi` (reusable)
Spending limit configuration
```json theme={"system"}
{
"amount": 10000,
"currency": "usd",
"frequency": "monthly"
}
```
Policy overrides
**Auth:** User only
**Response:**
```json theme={"system"}
{
"cardId": "card_abc123",
"displayName": "Shopping Card",
"status": "active",
"last4": "4242",
"agentId": "agent_abc123"
}
```
***
### card.list
List cards. Scoped to assigned cards when using agent authentication.
Maximum results to return (default: 50)
**Auth:** Both (User or Agent)
**Response:**
```json theme={"system"}
{
"cards": [
{
"cardId": "card_abc123",
"displayName": "Shopping Card",
"status": "active",
"last4": "4242",
"usage": "multi",
"createdAt": 1706745600000
}
],
"hasMore": false
}
```
***
### card.lock
Temporarily lock a card, preventing all transactions.
Card public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"cardId": "card_abc123",
"status": "locked"
}
```
***
### card.unlock
Unlock a previously locked card.
Card public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"cardId": "card_abc123",
"status": "active"
}
```
***
### card.cancel
Permanently cancel a card. This action cannot be undone.
Card public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"cardId": "card_abc123",
"status": "canceled"
}
```
***
### card.policy.update
Update per-card policy overrides.
Card public ID
Policy configuration. Available options:
* `requireIntent`: Require intent declaration before access
* `requireApproval`: Require explicit approval for intents
* `autoApproveBelow`: Auto-approve intents below this amount (cents)
* `allowedMccs`: Array of allowed merchant category codes
* `blockedMccs`: Array of blocked merchant category codes
* `limits`: Per-auth, daily, or monthly limits
Card usage type: `single` or `multi`
Card expiration timestamp (milliseconds)
**Auth:** User only
**Response:**
```json theme={"system"}
{
"cardId": "card_abc123",
"policy": {
"requireIntent": true,
"autoApproveBelow": 5000
},
"usage": "multi",
"expiresAt": null
}
```
***
## Intents
Tools for declaring spending intents. **Agent authentication only.**
### intent.create
Create a new spending intent before making a purchase.
Card public ID
Description of the intended purchase
Client-provided intent ID for idempotency
Expected transaction amount (in cents)
Expected currency (default: `usd`)
Expected merchant name
Expected merchant category codes
Allowed amount variance (in cents)
Allowed percentage variance
Intent time-to-live in minutes
Custom metadata
**Auth:** Agent only
**Response:**
```json theme={"system"}
{
"intentId": "int_abc123",
"clientIntentId": "my-intent-001",
"status": "pending",
"expiresAt": 1706749200000
}
```
***
### intent.list
List intents for the agent's cards.
Filter by card ID
Maximum results to return (default: 50)
**Auth:** Agent only
**Response:**
```json theme={"system"}
{
"intents": [
{
"intentId": "int_abc123",
"clientIntentId": "my-intent-001",
"cardId": "card_abc123",
"status": "pending",
"summary": "Purchase development tools",
"expectedAmount": 9900,
"expiresAt": 1706749200000,
"createdAt": 1706745600000
}
]
}
```
***
### intent.autoApprove.configure
Configure auto-approval thresholds at the customer, agent, or card level.
Configure for a specific agent
Configure for a specific card
Whether to require approval
Auto-approve intents below this amount (cents)
**Auth:** User only
**Response:**
```json theme={"system"}
{
"agentId": "agent_abc123",
"requireApproval": true,
"autoApproveBelow": 5000
}
```
***
## Access
Tools for requesting card credentials. **Agent authentication only.**
### access.request
Request access to card credentials for an approved intent.
Card public ID
Intent public ID or client-provided ID
Access request summary
Expected amount (cents)
Expected currency
Merchant name
Reason for access
Client context
**Auth:** Agent only
**Response (granted):**
```json theme={"system"}
{
"accessEventId": "acc_abc123",
"status": "granted",
"expiresAt": 1706746200000,
"card": {
"pan": "4111111111114242",
"cvc": "123",
"expiryMonth": "12",
"expiryYear": "2027"
}
}
```
**Response (denied):**
```json theme={"system"}
{
"accessEventId": "acc_abc123",
"status": "denied",
"reasons": ["intent_required", "amount_exceeds_limit"]
}
```
Card credentials are sensitive. The `card` object is only returned when access is granted and should be used immediately.
***
### access.events.list
List access events for the agent's cards.
Filter by card ID
Maximum results to return (default: 50)
**Auth:** Agent only
**Response:**
```json theme={"system"}
{
"events": [
{
"accessEventId": "acc_abc123",
"cardId": "card_abc123",
"status": "granted",
"summary": "Purchase development tools",
"expectedAmount": 9900,
"grantedAt": 1706745600000,
"expiresAt": 1706746200000,
"consumedAt": 1706745700000,
"createdAt": 1706745600000
}
]
}
```
***
## Transactions
Tools for viewing transaction history.
### transaction.list
List transactions. Scoped to agent's cards when using agent authentication.
Filter by card ID
Maximum results to return (default: 50)
**Auth:** Both (User or Agent)
**Response:**
```json theme={"system"}
{
"transactions": [
{
"transactionId": "txn_abc123",
"type": "authorization",
"status": "completed",
"amount": 9900,
"currency": "usd",
"merchant": {
"name": "GitHub Inc",
"mcc": "5734",
"city": "San Francisco",
"country": "US"
},
"createdAt": 1706745600000
}
],
"hasMore": false
}
```
***
### transaction.get
Fetch details of a single transaction.
Transaction public ID
**Auth:** User only
**Response:**
```json theme={"system"}
{
"transactionId": "txn_abc123",
"type": "authorization",
"status": "completed",
"amount": 9900,
"currency": "usd",
"merchant": {
"name": "GitHub Inc",
"mcc": "5734",
"city": "San Francisco",
"country": "US"
},
"cardId": "card_abc123",
"memo": null,
"createdAt": 1706745600000,
"settledAt": 1706832000000
}
```
***
## Disputes
Tools for managing transaction disputes.
### dispute.create
File a dispute for a transaction.
Transaction public ID
Dispute reason (e.g., `unauthorized`, `duplicate`, `not_received`)
Detailed description of the dispute
Custom metadata
**Auth:** User only
**Response:**
```json theme={"system"}
{
"disputeId": "dsp_abc123",
"transactionId": "txn_abc123",
"status": "submitted",
"reason": "unauthorized",
"createdAt": 1706745600000
}
```
***
### dispute.list
List all disputes for the customer.
Maximum results to return (default: 50)
**Auth:** User only
**Response:**
```json theme={"system"}
{
"disputes": [
{
"disputeId": "dsp_abc123",
"status": "under_review",
"reason": "unauthorized",
"amount": 9900,
"currency": "usd",
"createdAt": 1706745600000,
"resolvedAt": null
}
]
}
```
***
### dispute.update
Update a dispute with additional evidence or information.
Dispute public ID
Evidence to add
Updated description
Custom metadata
**Auth:** User only
**Response:**
```json theme={"system"}
{
"disputeId": "dsp_abc123",
"status": "under_review",
"updatedAt": 1706832000000
}
```
***
## Funding
Tools for managing account funding.
### funding.instructions.get
Get deposit instructions for funding the account.
**Auth:** User only
**Parameters:** None
**Response:**
```json theme={"system"}
{
"method": "crypto",
"currency": "USDC",
"network": "ethereum",
"depositAddress": "0x1234567890abcdef...",
"minDeposit": 100,
"instructions": "Send USDC to the deposit address. Funds typically arrive within 10-30 minutes."
}
```
***
### funding.history.list
List funding events (deposits, withdrawals, transfers).
Maximum results to return (default: 50)
**Auth:** User only
**Response:**
```json theme={"system"}
{
"events": [
{
"transactionId": "txn_abc123",
"type": "deposit",
"amount": 100000,
"currency": "usd",
"status": "completed",
"createdAt": 1706745600000,
"completedAt": 1706746800000
}
],
"hasMore": false
}
```
***
## Balance
Tools for checking account balance.
### balance.get
Get the current available balance.
**Auth:** Both (User or Agent)
**Parameters:** None
**Response:**
```json theme={"system"}
{
"available": 95000,
"held": 5000,
"currency": "usd"
}
```
* `available`: Funds available for spending
* `held`: Funds temporarily held for pending authorizations
* All amounts are in cents
# Quickstart
Source: https://docs.useproxy.ai/quickstart
Issue your first card in minutes
## Prerequisites
* A Proxy account ([sign up](https://dashboard.useproxy.ai))
* Your API key from the dashboard
## Authentication
All API requests require a Bearer token:
```bash theme={"system"}
Authorization: Bearer your_api_key
```
## Step 1: Create a Customer
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/customers \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"type": "consumer",
"email": "alice@example.com",
"name": { "first": "Alice", "last": "Smith" }
}'
```
## Step 2: Register an Agent
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/agents \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"externalId": "my-agent-123",
"name": "Shopping Agent"
}'
```
## Step 3: Issue a Card
```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/cards \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_xxx",
"agentId": "agent_xxx",
"usage": "multi"
}'
```
## Step 4: Declare Intent & Access Card
```bash theme={"system"}
# Declare intent
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/intents \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"purpose": "Purchase supplies from Amazon",
"expectedAmount": 5000,
"expectedMerchant": "Amazon"
}'
# Get card details
curl -X POST https://api.useproxy.ai/v1/cards/card_xxx/details \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"intentId": "int_xxx",
"purpose": "Purchase supplies from Amazon"
}'
```
## Next Steps
Deep dive into core concepts
Full API documentation