REST API

Complete reference for the ClawPay REST API.

Base URL

Production: https://api.useclawpay.app/v1
Sandbox:    https://api.sandbox.useclawpay.app/v1

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer sk_live_your_api_key

Vaults

Vaults are treasury accounts that hold your digital assets.

Create Vault

POST /v1/vaults

Request Body:

{
  "name": "Company Treasury",
  "currency": "USDC",
  "network": "solana",
  "initialDeposit": 10000.00,
  "metadata": {
    "department": "Finance",
    "costCenter": "CC-001"
  }
}

Response:

{
  "id": "vault_1a2b3c4d5e6f",
  "name": "Company Treasury",
  "currency": "USDC",
  "network": "solana",
  "balance": 10000.00,
  "depositAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "status": "active",
  "createdAt": "2024-01-15T10:30:00Z",
  "metadata": {
    "department": "Finance",
    "costCenter": "CC-001"
  }
}

List Vaults

GET /v1/vaults?limit=10&startingAfter=vault_abc123

Query Parameters:

Parameter

Type

Description

limit

integer

Number of results (1-100, default: 10)

startingAfter

string

Cursor for pagination

currency

string

Filter by currency (USDC, SOL, etc.)

status

string

Filter by status (active, frozen, closed)

Response:

{
  "data": [
    {
      "id": "vault_1a2b3c4d5e6f",
      "name": "Company Treasury",
      "balance": 10000.00,
      "currency": "USDC"
    }
  ],
  "hasMore": true,
  "nextCursor": "vault_xyz789"
}

Retrieve Vault

GET /v1/vaults/:id

Update Vault

PATCH /v1/vaults/:id

Request Body:

{
  "name": "Updated Treasury Name",
  "metadata": {
    "department": "Operations"
  }
}

Freeze Vault

POST /v1/vaults/:id/freeze

Temporarily freezes all transactions. Useful for security incidents.

Close Vault

POST /v1/vaults/:id/close

Withdraws remaining balance and permanently closes the vault.

Cards

Virtual debit cards linked to vaults.

Create Card

POST /v1/cards

Request Body:

{
  "vaultId": "vault_1a2b3c4d5e6f",
  "cardholderName": "John Doe",
  "spendingLimit": {
    "daily": 1000,
    "monthly": 25000,
    "perTransaction": 500
  },
  "allowedCategories": [
    "software",
    "cloud_services",
    "advertising"
  ],
  "billingAddress": {
    "line1": "123 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94103",
    "country": "US"
  }
}

Response:

{
  "id": "card_7g8h9i0j1k2l",
  "vaultId": "vault_1a2b3c4d5e6f",
  "cardholderName": "John Doe",
  "maskedNumber": "4242 •••• •••• 1234",
  "last4": "1234",
  "brand": "visa",
  "expiryMonth": 12,
  "expiryYear": 2027,
  "cvv": "123",
  "status": "active",
  "spendingLimit": {
    "daily": 1000,
    "monthly": 25000,
    "perTransaction": 500
  },
  "spent": {
    "today": 0,
    "thisMonth": 0
  },
  "createdAt": "2024-01-15T10:35:00Z"
}

List Cards

GET /v1/cards?vaultId=vault_123&status=active

Reveal Card Details

GET /v1/cards/:id/reveal

Returns full card number and CVV. Requires 2FA if enabled.

{
  "number": "4242424242421234",
  "cvv": "123",
  "expiryMonth": 12,
  "expiryYear": 2027
}

Freeze Card

POST /v1/cards/:id/freeze

Temporarily blocks transactions. Can be unfrozen later.

Cancel Card

POST /v1/cards/:id/cancel

Permanently cancels the card. Cannot be reversed.

Transactions

View transaction history and details.

List Transactions

GET /v1/transactions?vaultId=vault_123&limit=50

Query Parameters:

Parameter

Type

Description

vaultId

string

Filter by vault

cardId

string

Filter by card

status

string

pending, completed, failed, declined

minAmount

number

Minimum transaction amount

maxAmount

number

Maximum transaction amount

startDate

string

ISO 8601 date

endDate

string

ISO 8601 date

limit

integer

Results per page (1-100)

Response:

{
  "data": [
    {
      "id": "txn_m3n4o5p6q7r8",
      "vaultId": "vault_1a2b3c4d5e6f",
      "cardId": "card_7g8h9i0j1k2l",
      "amount": 49.99,
      "currency": "USD",
      "status": "completed",
      "merchant": {
        "name": "Amazon Web Services",
        "category": "cloud_services",
        "mcc": "5734"
      },
      "authorization": {
        "approvedBy": "system",
        "policyMatched": "whitelist_daily_limit"
      },
      "createdAt": "2024-01-15T14:22:33Z",
      "settledAt": "2024-01-15T14:22:35Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "txn_abc123"
}

Retrieve Transaction

GET /v1/transactions/:id

Transaction Metadata

View zero-knowledge encrypted metadata:

GET /v1/transactions/:id/metadata

Only accessible to vault owners and transaction counterparties.

Authorization Policies

Define spending rules for vaults.

Set Authorization Policy

POST /v1/vaults/:id/authorization-policy

Request Body:

{
  "type": "whitelist_only",
  "dailyLimit": 5000,
  "weeklyLimit": 30000,
  "monthlyLimit": 100000,
  "currency": "USDC",
  "merchants": [
    "amazon.com",
    "aws.amazon.com",
    "vercel.com"
  ],
  "categories": [
    "cloud_services",
    "software",
    "advertising"
  ],
  "requiresApproval": {
    "above": 1000,
    "minApprovers": 2,
    "approvers": [
      "[email protected]",
      "[email protected]"
    ],
    "timeoutMinutes": 60
  },
  "timeRestrictions": {
    "allowedDays": ["monday", "tuesday", "wednesday", "thursday", "friday"],
    "allowedHours": {
      "start": "09:00",
      "end": "17:00",
      "timezone": "America/New_York"
    }
  },
  "zkProofRequired": true
}

Get Authorization Policy

GET /v1/vaults/:id/authorization-policy

Delete Authorization Policy

DELETE /v1/vaults/:id/authorization-policy

Removes all restrictions (not recommended for production).

Transfers

Move funds between vaults or to external addresses.

Create Transfer

POST /v1/transfers

Request Body:

{
  "sourceVaultId": "vault_1a2b3c4d5e6f",
  "destinationVaultId": "vault_xyz789",
  "amount": 5000.00,
  "currency": "USDC",
  "memo": "Q1 Marketing Budget",
  "idempotencyKey": "transfer_20240115_001"
}

Response:

{
  "id": "transfer_s9t0u1v2w3x4",
  "sourceVaultId": "vault_1a2b3c4d5e6f",
  "destinationVaultId": "vault_xyz789",
  "amount": 5000.00,
  "currency": "USDC",
  "status": "completed",
  "memo": "Q1 Marketing Budget",
  "createdAt": "2024-01-15T15:00:00Z",
  "completedAt": "2024-01-15T15:00:02Z"
}

External Transfer

POST /v1/transfers/external

Transfer to an external Solana address:

{
  "sourceVaultId": "vault_1a2b3c4d5e6f",
  "destinationAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
  "amount": 1000.00,
  "currency": "USDC",
  "network": "solana",
  "priority": "high"
}

Webhooks

Configure webhook endpoints to receive real-time events.

Create Webhook

POST /v1/webhooks

Request Body:

{
  "url": "https://api.yourcompany.com/webhooks/clawpay",
  "events": [
    "transaction.created",
    "transaction.completed",
    "transaction.failed",
    "authorization.required",
    "card.created",
    "card.declined",
    "vault.balance_low"
  ],
  "secret": "whsec_your_secret_key",
  "metadata": {
    "environment": "production"
  }
}

List Webhooks

GET /v1/webhooks

Delete Webhook

DELETE /v1/webhooks/:id

Test Webhook

POST /v1/webhooks/:id/test

Sends a test event to verify your endpoint.

Balances

Query real-time balance information.

Get Vault Balance

GET /v1/vaults/:id/balance

Response:

{
  "vaultId": "vault_1a2b3c4d5e6f",
  "available": 9500.00,
  "pending": 500.00,
  "total": 10000.00,
  "currency": "USDC",
  "lastUpdated": "2024-01-15T15:30:00Z"
}

Get Balance History

GET /v1/vaults/:id/balance/history?period=30d

Returns daily balance snapshots.

Rate Limits

Check your current rate limit status:

GET /v1/rate-limit

Response:

{
  "limit": 600,
  "remaining": 542,
  "reset": "2024-01-15T16:00:00Z",
  "tier": "pro"
}

Errors

All errors follow this format:

{
  "error": {
    "type": "invalid_request_error",
    "code": "vault_not_found",
    "message": "No vault found with ID vault_123",
    "param": "vaultId",
    "requestId": "req_abc123xyz"
  }
}

Error Types

Type

Description

authentication_error

Invalid API key or expired session

invalid_request_error

Malformed request or invalid parameters

permission_error

Insufficient permissions for operation

rate_limit_error

Too many requests

server_error

Internal server error (contact support)

Common Error Codes

vault_not_found - Vault ID doesn't exist
insufficient_balance - Not enough funds for operation
card_declined - Card transaction declined
authorization_failed - Transaction violates authorization policy
invalid_currency - Unsupported currency
duplicate_idempotency_key - Request already processed

Idempotency

Prevent duplicate requests by including an idempotency key:

POST /v1/transfers
Idempotency-Key: transfer_20240115_001

If the same key is used within 24 hours, the original response is returned without creating a duplicate.

Pagination

List endpoints support cursor-based pagination:

{
  "data": [...],
  "hasMore": true,
  "nextCursor": "cursor_abc123"
}

Use nextCursor for the next page:

GET /v1/transactions?startingAfter=cursor_abc123

Versioning

The API version is included in the URL: /v1/

Breaking changes will be released in new versions (/v2/, etc.). Non-breaking changes are added to existing versions.

Next Steps

PreviousWebhooks NextError Codes

Last updated 1 hour ago

Good evening

hashtagBase URL

hashtagAuthentication

hashtagVaults

hashtagCreate Vault

hashtagList Vaults

hashtagRetrieve Vault

hashtagUpdate Vault

hashtagFreeze Vault

hashtagClose Vault

hashtagCards

hashtagCreate Card

hashtagList Cards

hashtagReveal Card Details

hashtagFreeze Card

hashtagCancel Card

hashtagTransactions

hashtagList Transactions

hashtagRetrieve Transaction

hashtagTransaction Metadata

hashtagAuthorization Policies

hashtagSet Authorization Policy

hashtagGet Authorization Policy

hashtagDelete Authorization Policy

hashtagTransfers

hashtagCreate Transfer

hashtagExternal Transfer

hashtagWebhooks

hashtagCreate Webhook

hashtagList Webhooks

hashtagDelete Webhook

hashtagTest Webhook

hashtagBalances

hashtagGet Vault Balance

hashtagGet Balance History

hashtagRate Limits

hashtagErrors

hashtagError Types

hashtagCommon Error Codes

hashtagIdempotency

hashtagPagination

hashtagVersioning

hashtagNext Steps

Base URL

Authentication

Vaults

Create Vault

List Vaults

Retrieve Vault

Update Vault

Freeze Vault

Close Vault

Cards

Create Card

List Cards

Reveal Card Details

Freeze Card

Cancel Card

Transactions

List Transactions

Retrieve Transaction

Transaction Metadata

Authorization Policies

Set Authorization Policy

Get Authorization Policy

Delete Authorization Policy

Transfers

Create Transfer

External Transfer

Webhooks

Create Webhook

List Webhooks

Delete Webhook

Test Webhook

Balances

Get Vault Balance

Get Balance History

Rate Limits

Errors

Error Types

Common Error Codes

Idempotency

Pagination

Versioning

Next Steps