> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.seismic-cards.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# Card funding (wallet & BYO)

> Fund prepaid cards with stablecoins using Seismic wallet service or a bring-your-own (BYO) external wallet.

Prepaid cards are topped up from **stablecoins** deposited for the cardholder (applicant). Seismic exposes one receive address and a one-click fund call. You choose the product mode **per program**.

| Mode                       | Who sends                                        | Your job                                                                                    |
| -------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `wallet_service` (default) | End-user (or you) to Seismic’s deposit address   | Show deposit address → wait for balance → `fund-from-wallet`                                |
| `byo_wallet`               | End-user **from** a wallet address you configure | Store their wallet → show deposit address → they send from that wallet → `fund-from-wallet` |

Both modes use the **same** deposit address and the **same** `POST /v1/cards/{id}/fund-from-wallet` call. BYO only adds the configured send-from wallet on the program and on deposit-address responses.

<Note>
  Upstream issuer / crypto-rail names never appear in responses. You only see Seismic API fields.
</Note>

## 1. Set the program funding mode

### Wallet service (default)

```bash theme={null}
curl -s -X PUT 'https://api.seismic-cards.systems/v1/programs/PROGRAM_ID/funding-config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "wallet_service",
    "preferred_chain": "BASE",
    "preferred_currency": "USDC"
  }'
```

### Bring-your-own (BYO) wallet

`byo.address` is **required** — the user’s external wallet they will send from.

```bash theme={null}
curl -s -X PUT 'https://api.seismic-cards.systems/v1/programs/PROGRAM_ID/funding-config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "byo_wallet",
    "preferred_chain": "BASE",
    "preferred_currency": "USDC",
    "byo": {
      "address": "0xUserWalletAddress",
      "chain": "BASE",
      "currency": "USDC",
      "provider": "metamask"
    }
  }'
```

Read back with `GET /v1/programs/{id}/funding-config`.

## 2. Get the deposit address

After the applicant has completed issuer KYC (`issuerKycReady: true`):

```bash theme={null}
curl -s 'https://api.seismic-cards.systems/v1/applicants/APPLICANT_ID/funding/deposit-address?program_id=PROGRAM_ID&chain=BASE&currency=USDC' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Example **BYO** response:

```json theme={null}
{
  "data": {
    "applicant_id": "app_abc123",
    "mode": "byo_wallet",
    "address": "0xDepositReceiveAddress",
    "currency": "USDC",
    "chain": "BASE",
    "instructions": "Send from your configured external wallet to this address, then call fund-from-wallet on the card.",
    "byo_wallet": {
      "address": "0xUserWalletAddress",
      "chain": "BASE",
      "currency": "USDC",
      "provider": "metamask"
    }
  }
}
```

* **`address`** — always the **receive** address (send *to* this).
* **`byo_wallet.address`** — only in `byo_wallet` mode; the configured **send-from** wallet.

## 3. Check balances

```bash theme={null}
curl -s 'https://api.seismic-cards.systems/v1/applicants/APPLICANT_ID/funding/balances' \
  -H 'Authorization: Bearer YOUR_TOKEN'
```

Use `available_to_fund_usd` (or deposit balances) to know when you can top up the card.

## 4. Fund the card

```bash theme={null}
curl -s -X POST 'https://api.seismic-cards.systems/v1/cards/CARD_ID/fund-from-wallet' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: fund-CARD_ID-25' \
  -d '{ "amount": "25.00" }'
```

This swaps deposited stables → USD and credits the prepaid card spend pot. Minimums are enforced by the rail (typically ≥ \$0.50).

## Flow

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant API as Seismic API
  participant User as End-user wallet

  App->>API: PUT funding-config (wallet_service or byo_wallet)
  App->>API: GET deposit-address
  API-->>App: receive address (+ byo send-from if BYO)
  User->>API: Send USDC to receive address
  App->>API: GET funding/balances
  App->>API: POST cards/{id}/fund-from-wallet
  API-->>App: Card spend balance updated
```

## Errors to expect

| Situation                                        | Typical result                                              |
| ------------------------------------------------ | ----------------------------------------------------------- |
| `byo_wallet` without `byo.address`               | `400` — address required                                    |
| Applicant KYC incomplete                         | `400` — no issuer account yet                               |
| Amount below rail minimum / insufficient deposit | `400` / issuer error                                        |
| Wrong chain or currency                          | Deposit may not credit — match `preferred_*` / query params |

## Related

* [Programs & accounts](/concepts/programs-accounts) — create the program first
* [Cards](/concepts/cards) — issue the prepaid card before funding
* API reference: `PUT /v1/programs/{id}/funding-config`, `GET …/funding/deposit-address`, `POST /v1/cards/{id}/fund-from-wallet`