> For the complete documentation index, see [llms.txt](https://wally-3.gitbook.io/wally-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wally-3.gitbook.io/wally-docs/technical/index-1.md).

# API Reference

> Technical documentation for Wally's communication layers.

***

## GraphQL API

The primary interface for frontend and mobile apps. Built with NestJS (code-first approach).

### Access Points

* **Development**: `http://localhost:4000/graphql`
* **Production**: Available at the deployed API URL

### Core Operations

| Module         | Queries                         | Mutations                                         |
| -------------- | ------------------------------- | ------------------------------------------------- |
| **Auth**       | `me`                            | `login`, `register`, `magicLink`, `googleAuth`    |
| **User**       | `user`, `users`                 | `updateProfile`, `updateKyc`                      |
| **Blockchain** | `balance`, `accountInfo`        | `sendPayment`, `createTrustline`                  |
| **Project**    | `projects`, `project`           | `createProject`, `contribute`, `migrateToEscrow`  |
| **Savings**    | `savingsVaults`, `savingsVault` | `createVault`, `deposit`, `withdraw`              |
| **Blend**      | `poolInfo`, `userPosition`      | `submitBlendTx`                                   |
| **Provider**   | `providers`, `provider`         | `createProvider`, `verifyProvider`                |
| **Remittance** | `remittances`                   | `createRemittance`, `fundEscrow`, `releaseEscrow` |
| **Merchant**   | `apiKeys`, `paymentRequests`    | `createApiKey`, `createPaymentRequest`            |

### Authentication

* Most queries/mutations require a JWT token in the `Authorization` header
* Public queries (providers list, pool info) don't require authentication
* Guard: `GqlAuthGuard` on protected resolvers

***

## Merchant API (REST)

For external integrations and programmatic payments.

### Endpoints

| Method | Path                             | Description                |
| ------ | -------------------------------- | -------------------------- |
| POST   | `/merchant/api-keys`             | Generate new API key       |
| POST   | `/merchant/payment-requests`     | Create payment request     |
| GET    | `/merchant/payment-requests/:id` | Get payment request status |

### Authentication

* API key in `X-API-Key` header
* Generated per merchant account

### Webhooks

* Configurable webhook URL per API key
* Fires on payment completion
* Includes payment request ID, amount, status, and transaction hash

***

## Environment Variables

Key variables required in `apps/api/.env`:

```
DATABASE_URL          # Neon PostgreSQL connection string
JWT_SECRET            # Secret for signing JWT tokens
STELLAR_NETWORK       # TESTNET or PUBLIC
STELLAR_PLATFORM_SECRET  # Platform account for escrow operations
HORIZON_URL           # Stellar Horizon endpoint
SOROBAN_RPC_URL       # Soroban RPC endpoint
BLEND_POOL_CONTRACT_ID   # Blend Capital pool contract
BLEND_USDC_ASSET_ID      # USDC asset identifier for Blend
TRUSTLESSWORK_API_KEY    # TrustlessWork API authentication
GOOGLE_CLIENT_ID         # Google OAuth client ID
GOOGLE_CLIENT_SECRET     # Google OAuth client secret
```
