Overview Quickstart Authentication Payment Flow Wallets & Funding Refunds Spending Controls API Reference

Wallets & Funding

APISettle uses non-custodial Solana wallets for all payments. This page covers wallet creation, spending delegation, and funding via fiat on-ramps.

Wallet types

Embedded (Turnkey)

Auto-provisioned wallets backed by Turnkey's AWS Nitro enclaves. Private keys never leave the secure enclave. Best for most integrations.

External

Bring your own Solana wallet. Register the public address with APISettle. You manage signing and key storage.

Non-custodial by default: APISettle never holds private keys. Embedded wallets use Turnkey's secure infrastructure. Your funds stay in your wallet at all times.

Provision an embedded wallet

POST /v1/wallets/provision

Creates a new Solana wallet backed by Turnkey. Each user gets their own sub-organization with isolated key material.

provision.js

// Provision an embedded Turnkey wallet
const res = await fetch('https://api.apisettle.com/v1/wallets/provision', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${JWT}`,
    'Content-Type': 'application/json',
  },
})

const wallet = await res.json()
// {
//   id: "wal_...",
//   address: "7xKXtg...",
//   chain: "solana",
//   provider: "turnkey",
//   delegation_status: "none"
// }

Register an external wallet

POST /v1/wallets

If you already have a Solana wallet, register its public address. Delegation and funding work the same way.

external-wallet.js

// Register an external Solana wallet
const res = await fetch('https://api.apisettle.com/v1/wallets', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${JWT}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    address: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
    chain: 'solana',
  }),
})

Spending delegation

Before a wallet can settle payments, it must delegate spending authority to APISettle. This is an on-chain approval (like an ERC-20 allowance) that lets the platform execute transfers up to a capped amount.

Capped. Delegation is limited to a set allowance. The platform can never spend more than the allowance or the wallet balance, whichever is lower.

Revocable. Users can revoke delegation at any time, immediately blocking future transfers.

Transparent. Delegation is an on-chain operation. You can verify it independently on Solana.

delegate.js

// Set up spending delegation
const res = await fetch(
  `https://api.apisettle.com/v1/wallets/${walletId}/delegate`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${JWT}` },
  },
)

const { delegation_status } = await res.json()
// delegation_status: "active"
// Consumer can now settle payments through this wallet

Delegation states

Status	Meaning
none	No delegation set up. Cannot settle payments.
pending	Delegation transaction submitted, awaiting confirmation.
active	Delegation confirmed. Wallet can settle payments.
revoked	User revoked delegation. No further transfers possible.

Fiat deposits

POST /v1/deposits/fiat

Fund wallets with credit card or bank transfer via Coinbase or Transak. Funds settle directly to the user's wallet — APISettle never holds the money.

deposit.js

// Create a fiat deposit session
const res = await fetch('https://api.apisettle.com/v1/deposits/fiat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${JWT}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: '50000000',    // $50.00
    asset: 'USDC',
    provider: 'coinbase',   // or "transak"
  }),
})

const { checkout_url, wallet_id } = await res.json()
// Redirect user to checkout_url to complete the deposit
// Wallet is auto-provisioned if user doesn't have one yet

Deposit limits

Constraint	Value
Minimum deposit	$1.00 (1,000,000 micro-units)
Maximum deposit	$10,000 (10,000,000,000 micro-units)
Supported asset	USDC

Lazy provisioning: If the user doesn't have a wallet yet, POST /deposits/fiat automatically provisions an embedded wallet and USDC token account before creating the checkout session.

Checking wallet readiness

POST /v1/wallets/:id/onboarding

Check whether a wallet has everything it needs to settle payments: token account, balance, and active delegation.

onboarding.js

// Check if wallet is ready for payments
const res = await fetch(
  `https://api.apisettle.com/v1/wallets/${walletId}/onboarding`,
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${JWT}` },
  },
)

const status = await res.json()
// {
//   has_token_account: true,
//   has_balance: true,
//   delegation_status: "active",
//   ready: true
// }

Payment Flow Refunds