REST API Reference

This reference documents the Swig Developer Portal REST API endpoints.

Base URLs

Environment	URL
Portal API	`https://dashboard.onswig.com`
Paymaster API	`https://api.onswig.com`

Authentication

All API requests require authentication via API key:

Authorization: Bearer sk_your_api_key

API keys are created in the Developer Portal and have the format sk_<64-hex-characters>.

Endpoints

Policies

Get Policy

Retrieve a policy by ID. Request:

GET /api/v1/policies/{policyId}

Headers:

Authorization: Bearer sk_your_api_key

Path Parameters:

Parameter	Type	Description
`policyId`	string	The policy ID (CUID format)

Response:

{
  "id": "clx1234567890abcdef",
  "name": "user-wallet-policy",
  "description": "Standard user wallet with transfer limits",
  "authority": {
    "type": "Ed25519",
    "publicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
  },
  "actions": [
    { "type": "SolLimit", "amount": "1000000000" },
    { "type": "TokenLimit", "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "amount": "1000000" }
  ]
}

cURL Example:

curl -X GET "https://dashboard.onswig.com/api/v1/policies/clx1234567890abcdef" \
  -H "Authorization: Bearer sk_your_api_key"

Wallets

Create Wallet

Create a new Swig wallet using a policy. Request:

POST /api/v1/wallet/create

Headers:

Authorization: Bearer sk_your_api_key
Content-Type: application/json

Request Body:

Field	Type	Required	Description
`policyId`	string	Yes	Policy ID to use
`network`	string	Yes	`"mainnet"` or `"devnet"`
`paymasterPubkey`	string	No	Paymaster public key. When provided, the paymaster signs and sends the transaction. When omitted, an unsigned transaction is returned.
`swigId`	string	No	Custom Swig ID (auto-generated if omitted)
`signerId`	string	No	Signer ID from the dashboard (alternative to `walletAddress` + `walletType`)
`walletAddress`	string	No	Wallet public key to use as the authority (alternative to `signerId`). Must be provided together with `walletType`.
`walletType`	string	No	Authority type: `ED25519`, `ED25519_SESSION`, `SECP256K1`, `SECP256K1_SESSION`, `SECP256R1`, or `SECP256R1_SESSION` (alternative to `signerId`). Must be provided together with `walletAddress`.
`maxDurationSlots`	string	No	Maximum session duration in slots. Only valid for session authority types.

You can specify the wallet authority in two ways: either by providing a signerId from the dashboard, or by supplying a walletAddress and walletType directly. See Creating a Swig Wallet for details.

Request Example (with paymaster):

{
  "policyId": "clx1234567890abcdef",
  "network": "devnet",
  "paymasterPubkey": "A1dBRAaYUHyUzyQLGYzHrQzpYy9xTVXCaMnHx4RuEGY5"
}

Request Example (without paymaster — self-send flow):

{
  "policyId": "clx1234567890abcdef",
  "network": "devnet"
}

Request Example (with wallet address and type):

{
  "policyId": "clx1234567890abcdef",
  "network": "devnet",
  "paymasterPubkey": "A1dBRAaYUHyUzyQLGYzHrQzpYy9xTVXCaMnHx4RuEGY5",
  "walletAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "walletType": "ED25519"
}

Response (with paymaster):

{
  "data": {
    "swigId": "a1b2c3d4e5f67890",
    "swigAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "signature": "5wHu1qwD7g4p3zWxF..."
  },
  "error": null
}

Response (without paymaster):

{
  "data": {
    "swigId": "a1b2c3d4e5f67890",
    "swigAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "transaction": "BASE58_ENCODED_VERSIONED_TRANSACTION..."
  },
  "error": null
}

Response Field	Type	Present When	Description
`swigId`	string	Always	Swig wallet identifier
`swigAddress`	string	Always	On-chain PDA address
`signature`	string	With paymaster	Transaction signature
`transaction`	string	Without paymaster	Base58-encoded unsigned `VersionedTransaction`

cURL Example (with paymaster):

curl -X POST "https://dashboard.onswig.com/api/v1/wallet/create" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "policyId": "clx1234567890abcdef",
    "network": "devnet",
    "paymasterPubkey": "A1dBRAaYUHyUzyQLGYzHrQzpYy9xTVXCaMnHx4RuEGY5"
  }'

cURL Example (without paymaster):

curl -X POST "https://dashboard.onswig.com/api/v1/wallet/create" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "policyId": "clx1234567890abcdef",
    "network": "devnet"
  }'

Paymaster

Submit a transaction for sponsorship. Request:

POST /sponsor

Base URL: https://api.onswig.com Headers:

Authorization: Bearer sk_your_api_key
Content-Type: application/json

Request Body:

Field	Type	Required	Description
`base58_encoded_transaction`	string	Yes	Base58-encoded transaction
`network`	string	No	`"mainnet"` or `"devnet"`

Request Example:

{
  "base58_encoded_transaction": "BASE58_ENCODED_TX_HERE",
  "network": "devnet"
}

Response:

{
  "request_id": "req_abc123",
  "signature": "5wHu1qwD7g4p3zWxF...",
  "spent_by_paymaster": 5000
}

Response Fields:

Field	Type	Description
`request_id`	string	Unique request identifier
`signature`	string	Transaction signature
`spent_by_paymaster`	number	Lamports spent by paymaster

Sign Transaction

Sign a transaction without sending. Request:

POST /sign

Base URL: https://api.onswig.com Headers:

Authorization: Bearer sk_your_api_key
Content-Type: application/json

Request Body:

Field	Type	Required	Description
`base58_encoded_transaction`	string	Yes	Base58-encoded transaction
`network`	string	No	`"mainnet"` or `"devnet"`

Response:

{
  "request_id": "req_abc123",
  "signed_transaction": "BASE58_ENCODED_SIGNED_TX"
}

Health Check

Check paymaster service health. Request:

GET /health

Base URL: https://api.onswig.com Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T12:00:00Z"
}

Data Types

Policy

interface Policy {
  id: string;
  name: string;
  description: string | null;
  authority: AuthorityConfig | null;
  actions: ActionConfig[];
}

AuthorityConfig

type AuthorityConfig =
  | { type: 'Ed25519'; publicKey: string }
  | { type: 'Ed25519Session'; publicKey: string; maxDurationSlots: string }
  | { type: 'Secp256k1'; publicKey: string }
  | { type: 'Secp256k1Session'; publicKey: string; maxDurationSlots: string }
  | { type: 'Secp256r1'; publicKey: string }
  | { type: 'Secp256r1Session'; publicKey: string; maxDurationSlots: string };

ActionConfig

type ActionConfig =
  // General
  | { type: 'All' }
  | { type: 'AllButManageAuthority' }
  | { type: 'ManageAuthority' }

  // SOL
  | { type: 'SolLimit'; amount: string }
  | { type: 'SolRecurringLimit'; recurringAmount: string; window: string }
  | { type: 'SolDestinationLimit'; amount: string; destination: string }
  | { type: 'SolRecurringDestinationLimit'; recurringAmount: string; window: string; destination: string }

  // Token
  | { type: 'TokenLimit'; mint: string; amount: string }
  | { type: 'TokenRecurringLimit'; mint: string; recurringAmount: string; window: string }
  | { type: 'TokenDestinationLimit'; mint: string; amount: string; destination: string }
  | { type: 'TokenRecurringDestinationLimit'; mint: string; recurringAmount: string; window: string; destination: string }

  // Program
  | { type: 'Program'; programId: string }
  | { type: 'ProgramAll' }
  | { type: 'ProgramCurated' }

  // Staking
  | { type: 'StakeLimit'; amount: string }
  | { type: 'StakeRecurringLimit'; recurringAmount: string; window: string }
  | { type: 'StakeAll' }

  // Sub-accounts
  | { type: 'SubAccount' };

WalletType

type WalletType =
  | 'ED25519'
  | 'ED25519_SESSION'
  | 'SECP256K1'
  | 'SECP256K1_SESSION'
  | 'SECP256R1'
  | 'SECP256R1_SESSION';

CreateWalletRequest

interface CreateWalletRequest {
  policyId: string;
  network: 'mainnet' | 'devnet';
  /** Optional — omit for self-send flow */
  paymasterPubkey?: string;
  swigId?: string;
  signerId?: string;
  walletAddress?: string;
  walletType?: WalletType;
  maxDurationSlots?: string;
}

CreateWalletResponse

The response is a union type — the shape depends on whether a paymaster was provided.

/** Returned when paymasterPubkey is provided */
interface CreateWalletPaymasterResponse {
  swigId: string;
  swigAddress: string;
  signature: string;
}

/** Returned when paymasterPubkey is omitted */
interface CreateWalletTransactionResponse {
  swigId: string;
  swigAddress: string;
  /** Base58-encoded unsigned VersionedTransaction */
  transaction: string;
}

type CreateWalletResponse =
  | CreateWalletPaymasterResponse
  | CreateWalletTransactionResponse;

Error Responses

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

See Error Codes for a complete list.

Rate Limits

API requests are rate-limited based on your subscription tier:

Tier	Requests/Minute
FREE	60
PRO	300
ULTRA	600
ENTERPRISE	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642520400

SDKs

Use our SDKs for easier integration:

API SDK
Developer SDK

npm install @swig-wallet/api

import { SwigApiClient } from '@swig-wallet/api';

const client = new SwigApiClient({
  apiKey: 'sk_your_api_key',
  portalUrl: 'https://dashboard.onswig.com',
});

npm install @swig-wallet/developer

import { SwigClient } from '@swig-wallet/developer';

const client = new SwigClient({
  apiKey: 'sk_your_api_key',
  baseUrl: 'https://dashboard.onswig.com',
});

Next Steps

Error Codes - Understand API errors
SDK Examples - See the SDKs in action
Create Wallets - Full wallet creation guide

Basics

Payments

Developer Portal

Paymaster

Ethereum Onboarding

Passkeys

Advanced

REST API Reference

Base URLs

Authentication

Endpoints

Policies

Get Policy

Wallets

Create Wallet

Paymaster

Sign Transaction

Health Check

Data Types

Policy

AuthorityConfig

ActionConfig

WalletType

CreateWalletRequest

CreateWalletResponse

Error Responses

Rate Limits

SDKs

Next Steps

Basics

Payments

Developer Portal

Paymaster

Ethereum Onboarding

Passkeys

Advanced

​Base URLs

​Authentication

​Endpoints

​Policies

​Get Policy

​Wallets

​Create Wallet

​Paymaster

​Sponsor Transaction

​Sign Transaction

​Health Check

​Data Types

​Policy

​AuthorityConfig

​ActionConfig

​WalletType

​CreateWalletRequest

​CreateWalletResponse

​Error Responses

​Rate Limits

​SDKs

​Next Steps

Base URLs

Authentication

Endpoints

Policies

Get Policy

Wallets

Create Wallet

Paymaster

Sponsor Transaction

Sign Transaction

Health Check

Data Types

Policy

AuthorityConfig

ActionConfig

WalletType

CreateWalletRequest

CreateWalletResponse

Error Responses

Rate Limits

SDKs

Next Steps