> ## Documentation Index
> Fetch the complete documentation index at: https://docs.daimo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Base URL, authentication, errors, and core types

## Base URL

```
https://api.daimo.com
```

## Authentication

Endpoints use Bearer token authentication with your API key:

```
Authorization: Bearer YOUR_API_KEY
```

Some endpoints accept a **client secret** instead, passed in the request body or query string. Each session has its own client secret, returned when you create or retrieve the session. Client secrets are safe for client-side use since they only grant access to their specific session.

| Credential    | Format | Use                                                         |
| ------------- | ------ | ----------------------------------------------------------- |
| API key       | UUID   | Server-side. Create sessions, retrieve full details.        |
| Client secret | UUID   | Client-side, per-session. Set payment method, check status. |

## Error format

All errors return a JSON body:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameter",
    "message": "invalid session create request",
    "param": "body"
  }
}
```

| Field     | Type      | Description                                        |
| --------- | --------- | -------------------------------------------------- |
| `type`    | `string`  | Error category (see below)                         |
| `code`    | `string`  | Machine-readable error code                        |
| `message` | `string`  | Human-readable description                         |
| `param`   | `string?` | The parameter that caused the error, if applicable |

### Error types

| Type                    | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `authentication_error`  | Missing or invalid credentials                                  |
| `validation_error`      | Invalid request body or parameters                              |
| `invalid_request_error` | Valid request but cannot be processed (e.g. resource not found) |
| `api_error`             | Internal server error                                           |

### HTTP status codes

| Code  | Meaning                                  |
| ----- | ---------------------------------------- |
| `200` | Success                                  |
| `201` | Created                                  |
| `400` | Bad request, validation error            |
| `401` | Unauthorized, missing or invalid API key |
| `404` | Not found, session does not exist        |
| `500` | Internal server error                    |

## Session object

The full session object (returned with API key authentication):

```typescript theme={null}
{
  sessionId: string;        // 32-character hex ID
  status: SessionStatus;    // see below
  destination: {
    type: "evm";
    address: string;        // checksum-encoded destination address
    chainId: number;        // e.g. 8453
    chainName: string;      // e.g. "Base"
    tokenAddress: string;   // destination token address
    tokenSymbol: string;    // e.g. "USDC"
    amountUnits?: string;   // requested amount in token units
    calldata?: string;      // hex-encoded calldata for contract calls
    delivery?: {            // set once funds are delivered
      txHash: string;
      receivedUnits: string;
    };
  };
  display: {
    title: string;          // e.g. "Deposit to Acme"
    verb: string;           // e.g. "Deposit"
    themeCssUrl?: string;   // custom theme CSS URL
  };
  paymentMethod: PaymentMethod | null;
  metadata: Record<string, string> | null;
  clientSecret: string;     // per-session client credential
  createdAt: number;        // unix timestamp (seconds)
  expiresAt: number;        // unix timestamp (seconds)
}
```

Without an API key, `metadata` and `clientSecret` are omitted.

The `destination` above shows the EVM shape. For a Solana destination (USDC only), `destination` is instead:

```typescript theme={null}
{
  type: "solana";
  address: string;        // base58 destination address
  tokenAddress: string;   // USDC mint (base58)
  tokenSymbol: string;    // "USDC"
  amountUnits?: string;   // requested amount in token units
  delivery?: {            // set once funds are delivered
    txHash: string;       // Solana transaction signature
    receivedUnits: string;
  };
}
```

A Solana destination uses the token mint as `tokenAddress`, omits `chainId`, `chainName`, and `calldata`, and its `delivery.txHash` is a Solana transaction signature.

### SessionStatus

| Value                     | Description                                         |
| ------------------------- | --------------------------------------------------- |
| `requires_payment_method` | Waiting for user to choose how to deposit           |
| `waiting_payment`         | Payment method set, waiting for deposit transaction |
| `processing`              | Deposit detected, routing funds to destination      |
| `succeeded`               | Funds delivered to destination                      |
| `bounced`                 | Delivery failed, funds returned to refund address   |
| `expired`                 | Session timed out                                   |

### PaymentMethod

Three variants based on the source chain:

**EVM:**

```json theme={null}
{
  "type": "evm",
  "receiverAddress": "0x...",
  "source": {
    "address": "0x...",
    "chainId": 1,
    "chainName": "Ethereum",
    "tokenAddress": "0x...",
    "tokenSymbol": "USDC",
    "sentUnits": "10.00",
    "txHash": "0x..."
  },
  "createdAt": 1700000000
}
```

**Tron:**

```json theme={null}
{
  "type": "tron",
  "receiverAddress": "T...",
  "source": {
    "address": "T...",
    "chainId": 728126428,
    "chainName": "tron",
    "tokenAddress": "T...",
    "tokenSymbol": "USDT",
    "sentUnits": "10.00",
    "txHash": "..."
  },
  "createdAt": 1700000000
}
```

**Solana:**

```json theme={null}
{
  "type": "solana",
  "source": {
    "address": "So1...",
    "chainId": 501,
    "chainName": "solana",
    "tokenAddress": "EPjF...",
    "tokenSymbol": "USDC",
    "sentUnits": "10.00",
    "txHash": "..."
  },
  "createdAt": 1700000000
}
```

The `source` field is populated once the user's deposit transaction is detected. Before that, only `type`, `receiverAddress` (for EVM/Tron), and `createdAt` are present.

EVM and Tron are receiver-address flows. Solana is a sign-and-send flow: instead of a `receiverAddress`, the response returns a transaction payload for the wallet to execute in one click.

### Create payment method response

When creating a payment method, chain-specific fields are returned alongside the session:

* **Tron:** `tron.receiverAddress` (the Tron USDT address to send to), `tron.expiresAt`, and optionally `tron.deeplinks.trustWallet` for opening Trust Wallet's USDT on Tron send flow
* **Solana:** `solana.serializedTx` (hex-encoded serialized transaction for the wallet to sign and submit)
* **EVM:** no additional fields; the deposit address is the session's EVM deposit address