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

# Authentication & Response Formats

> API key setup, base URL, response format options, and error handling for the calldata API

## Base URL

```
https://api.paxoslabs.com
```

All endpoints are versioned under `/v2`.

## Authentication

Include your API key in the `x-api-key` header on every request:

```bash theme={null}
curl https://api.paxoslabs.com/v2/amplify/vaults \
  -H "x-api-key: pxl_your_public_id_your_secret"
```

API keys use the format `pxl_<public_id>_<secret>`. Obtain one from the [Paxos Labs dashboard](https://app.paxoslabs.com).

## Response Format

The three transaction-preparation endpoints (`deposit`, `withdraw`, `withdraw/cancel`) accept a `responseFormat` query parameter that controls which fields appear in the response:

| Format       | `data` (hex calldata) | `abi` / `functionName` / `args` | Default |
| ------------ | --------------------- | ------------------------------- | ------- |
| `encoded`    | Yes                   | No                              | Yes     |
| `full`       | Yes                   | Yes                             |         |
| `structured` | No                    | Yes                             |         |

### `encoded` (default)

Returns only the ABI-encoded calldata hex string. Use this when your signer accepts raw `data` fields (e.g. `eth_sendTransaction`).

```bash theme={null}
curl "https://api.paxoslabs.com/v2/amplify/deposit?\
vaultAddress=0xbbbb000000000000000000000000000000000001&\
depositAsset=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&\
depositAmount=1000000&\
userAddress=0x1234567890abcdef1234567890abcdef12345678&\
chainId=1" \
  -H "x-api-key: pxl_your_key"
```

```json theme={null}
{
  "transaction": {
    "to": "0xcccc000000000000000000000000000000000001",
    "data": "0x47e7ef24000000000000000000000000...",
    "value": "0"
  }
}
```

### `full`

Returns encoded calldata **plus** the ABI fragment, function name, and decoded args. Useful for debugging or when you need both representations.

```bash theme={null}
curl "https://api.paxoslabs.com/v2/amplify/deposit?\
vaultAddress=0xbbbb...&depositAsset=0xA0b8...&depositAmount=1000000&\
userAddress=0x1234...&chainId=1&responseFormat=full" \
  -H "x-api-key: pxl_your_key"
```

```json theme={null}
{
  "transaction": {
    "to": "0xcccc000000000000000000000000000000000001",
    "data": "0x47e7ef24000000000000000000000000...",
    "value": "0",
    "abi": [{ "type": "function", "name": "deposit", "inputs": [...], "outputs": [...] }],
    "functionName": "deposit",
    "args": ["0xA0b8...", "1000000", "999500", "0x1234..."]
  }
}
```

### `structured`

Returns the ABI fragment, function name, and args **without** encoded calldata. Use this when your library handles encoding (e.g. viem `encodeFunctionData`, ethers `interface.encodeFunctionData`).

```json theme={null}
{
  "transaction": {
    "to": "0xcccc000000000000000000000000000000000001",
    "value": "0",
    "abi": [{ "type": "function", "name": "deposit", "inputs": [...], "outputs": [...] }],
    "functionName": "deposit",
    "args": ["0xA0b8...", "1000000", "999500", "0x1234..."]
  }
}
```

## Error Handling

All error responses use a standard envelope:

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "vaultAddress is not a valid hex address",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.paxoslabs.dev/errors/BadRequest",
        "fieldViolations": [
          { "field": "vaultAddress", "description": "vaultAddress 0xinvalid is not a valid hex address." }
        ]
      }
    ]
  }
}
```

| HTTP Status | `error.status`       | Meaning                                       |
| ----------- | -------------------- | --------------------------------------------- |
| 400         | `INVALID_ARGUMENT`   | Malformed or missing parameters               |
| 401         | `UNAUTHENTICATED`    | Missing or malformed API key                  |
| 403         | `PERMISSION_DENIED`  | Invalid, inactive, or expired API key         |
| 404         | `NOT_FOUND`          | Vault not found for the given address + chain |
| 429         | `RESOURCE_EXHAUSTED` | Rate limit exceeded                           |
| 503         | `INTERNAL`           | RPC or upstream service unavailable           |