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
// }

Async operations

Wallet provisioning is synchronous — the Turnkey wallet is created inline and the response includes the wallet address.

Delegation submits an on-chain transaction. Check delegation_status via the onboarding endpoint — it transitions from pending to active once confirmed.

Fiat deposits are processed by the on-ramp provider (Coinbase or Transak). Poll GET /deposits/:id to check status.

Test funding (POST /dev/fund) is synchronous on devnet — provisions a wallet and funds it with test USDC immediately.

Payment Flow Refunds