# SPL Token Balance | Agent Integration Guide

This service is a **Level 402 X402-Enforced Resource Provider**. It provides institutional-grade SPL token balance verification, but access requires a valid settlement proof in the header.

## The Agentic Discovery Cycle

If you are an autonomous agent (e.g. OpenClaw) interacting with this service, follow this three-step lifecycle:

### 1. The 402 Challenge

Hit the endpoint with your query. If you haven't paid, you will receive an `HTTP 402 Payment Required`.

```bash
curl -i "https://preview.spl-token.signer-payer.me/api/v1/check-balance?wallet=<PUBKEY>&spl-token=So11111111111111111111111111111111111111112"
```

### 2. Facilitator Handshake & Proof Building

The 402 response includes an `accepts` array detailing supported costs (e.g., in USDC or SOL) along with a `capabilitiesUrl` pointing to the **pr402 Facilitator**.
Instead of hardcoding complex Solana PDA and rent logic, your agent should delegate transaction construction to the Facilitator API:

**Discovery (pr402):** On the facilitator host, prefer **`GET /api/v1/facilitator/capabilities`** — it includes **`agentManifest.payToSemantics`** (URL of **`/agent-payTo-semantics.json`**, machine-readable `payTo` rules and mint-allowlist metadata). Human runbook: **`/agent-integration.md`**. OpenAPI: **`/openapi.json`**.

**Mint allowlist:** If the operator sets **`PR402_ALLOWED_PAYMENT_MINTS`** (env or facilitator `parameters` table), only those base58 mints (plus native SOL **`11111111111111111111111111111111`** when listed) succeed on **`build-*`**, **`/verify`**, and **`/settle`**. This service’s **`accepts[].asset`** must match that policy or buyers fail at build time.

1. **Request the Build**: Make an HTTP POST to `<facilitator_base>/api/v1/facilitator/build-exact-payment-tx` using the specific requirement option you selected (e.g. your asset of choice) and your payer wallet public key.
2. **Local Cryptographic Signing**: The Facilitator returns an unsigned, Base64-encoded `VersionedTransaction` and a JSON template (`verifyBodyTemplate`). Decode the Base64 payload internally and sign it using your preferred Ed25519 cryptography library (e.g., Python's `solders` or `@solana/web3.js`). **Be sure to inject your signature at the correct index for your public key.**
3. **Repackage the Proof**: Overwrite the unsigned transaction inside the `verify_body_template` with your newly signed Base64 string.
    - **Optimization**: You can send this entire JSON block directly in the header (Raw JSON) or Base64-encode it (Base64 JSON). All X402 servers now support both.

### 3. Authorized Access

Include your proof in the **`PAYMENT-SIGNATURE`** header (x402 v2) on your subsequent request.

```bash
curl "https://preview.spl-token.signer-payer.me/api/v1/check-balance?wallet=<PUBKEY>&spl-token=So11111111111111111111111111111111111111112" \
  -H "PAYMENT-SIGNATURE: <JSON_OR_BASE64_PROOF>" \
  -H "X-Correlation-ID: <ANY_UUID>"
```

## Technical Specs

| Header | Purpose |
| --- | --- |
| `PAYMENT-SIGNATURE` | x402 v2 settlement proof. Raw JSON or base64 of JSON. |
| `PAYMENT-RESPONSE` | Returned by server after successful settlement (base64 JSON). |
| `X-Correlation-ID` | Recommended institutional telemetry (mirrored in response). |
| `X-API-Version` | Set to `1` for the finalized stable contract. |

For detailed machine discovery, see the canonical [OpenAPI manifest](/openapi.json).