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

# Quickstart

> Make your first cross-border payout against the Teel sandbox in 5 minutes

This guide walks you through making your first payout against the Teel **sandbox** environment. Sandbox provider APIs don't move real funds — perfect for end-to-end integration testing before you switch to production credentials.

<Steps>
  <Step title="Set your API key">
    Teel uses long-lived secret API keys (`sk_live_…` for production, `sk_test_…` for sandbox) presented as a bearer token. Same pattern as Stripe, OpenAI, Resend.

    Sandbox API keys are issued by the Teel onboarding team. Email **[support@teel.finance](mailto:support@teel.finance)** (or reach out to your dedicated onboarding contact) and we'll send your `sk_test_…` key through an encrypted channel. The plaintext is shown **exactly once** at creation; afterwards only the first 12 characters are retrievable for identification.

    ```bash theme={null}
    export TEEL_API_KEY="sk_test_<43 url-safe base64 chars>"
    ```

    Confirm the key works against the unauthenticated health endpoint and then against an authenticated read:

    ```bash theme={null}
    # 1. Health (no auth) — sanity check the host is reachable
    curl https://api-sandbox.teel.finance/health
    # → {"status":"ok","env":"..."}  (env echoes the deployment environment)

    # 2. Auth'd read — list your existing recipients
    curl https://api-sandbox.teel.finance/recipients \
      -H "Authorization: Bearer $TEEL_API_KEY"
    ```

    See the [Authentication page](/authentication) for key format, scopes, rotation, and revocation.
  </Step>

  <Step title="Check coverage">
    The public `/config/coverage` endpoint returns the matrix of currencies, rails, directions, and amount bounds Teel can route. No auth required — partners can hit it from their integration server's pre-flight checks before quoting.

    ```bash theme={null}
    curl https://api-sandbox.teel.finance/config/coverage
    ```

    Confirm your corridor (e.g. USD → PHP) is in the response before proceeding. See the [Coverage page](/coverage) for the full schema.
  </Step>

  <Step title="Create a recipient">
    Register the counterparty who will receive the payout. Recipients carry one or more payment methods — bank accounts or wallet addresses — that resolve currency-by-currency to the right provider at execution time.

    ```bash theme={null}
    curl -X POST https://api-sandbox.teel.finance/recipients \
      -H "Authorization: Bearer $TEEL_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "email": "payments@acme-ph.com",
        "isBusiness": "business",
        "businessName": "Acme Corp Philippines",
        "country": "PH",
        "transferType": "fiat",
        "paymentMethods": [
          {
            "currency": "PHP",
            "type": "bank",
            "rail": "bank_transfer",
            "bankName": "BDO",
            "accountNumber": "1234567890"
          }
        ]
      }'
    ```

    Request bodies are **camelCase** (`isBusiness`, `businessName`, `paymentMethods`); responses are snake\_case. Save the `id` from the response — that's your `recipientId`.

    The `Idempotency-Key` header is optional but recommended: a timeout-retry with the same key replays the cached response (24h window) instead of creating a duplicate recipient. See [`POST /recipients`](/api-reference/recipients/create) for every field.
  </Step>

  <Step title="Get a quote">
    Fetch the best available rate for your corridor. Quotes are short-lived (\~minutes) and carry an opaque `protocol` token you'll pass back at execution time to pin the route.

    ```bash theme={null}
    curl "https://api-sandbox.teel.finance/quotes/fiat-to-fiat/best?sourceCurrency=USD&targetCurrency=PHP&amount=1000&recipientId=$RECIPIENT_ID" \
      -H "Authorization: Bearer $TEEL_API_KEY"
    ```

    The response includes the exchange rate, fees, estimated delivery amount, a `quoteId` (use it to poll status in step 6), an opaque `protocol` route token (pass it back as `routeProtocol` at execution to pin this route), and the `expiresAt` timestamp. Use the quote before it expires.

    See the [Quotes pages](/api-reference/quotes/fiat-to-fiat-best) for the full quote families (onramp / offramp / fiat-to-fiat / fiat-to-stablecoin).
  </Step>

  <Step title="Execute the payout">
    Partners execute payouts through the RFQ (request-for-quote) endpoint. Re-send the corridor and amount from your quote, plus the `routeProtocol` token to pin the exact route you were quoted. Like recipient creation, this is `Idempotency-Key`-safe — Teel deduplicates retry attempts in a 24h window so a network timeout doesn't double-spend.

    ```bash theme={null}
    curl -X POST https://api-sandbox.teel.finance/rfq/execute \
      -H "Authorization: Bearer $TEEL_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "fromCurrency": "USD",
        "toCurrency": "PHP",
        "amount": 1000,
        "recipientId": "<recipient_id from step 3>",
        "routeProtocol": "<protocol token from step 4>"
      }'
    ```

    The response includes the `transactionId` and initial status. The payout begins processing immediately.
  </Step>

  <Step title="Track status">
    Two options: poll the status endpoint, or subscribe a webhook URL.

    **Poll:**

    ```bash theme={null}
    curl https://api-sandbox.teel.finance/rfq/status/<quoteId> \
      -H "Authorization: Bearer $TEEL_API_KEY"
    ```

    Status moves through `initiated → compliance_cleared → instructions_sent → collected → converting → settling → delivered` (terminal: `delivered` or `failed`).

    **Subscribe a webhook** for production payout monitoring instead of polling. Teel POSTs every status change to your URL with an HMAC-SHA256 signature header you verify with the secret returned at subscription creation:

    ```bash theme={null}
    curl -X POST https://api-sandbox.teel.finance/webhooks/subscriptions \
      -H "Authorization: Bearer $TEEL_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://your.app/teel-webhooks",
        "events": ["payout.created", "payout.status.updated"]
      }'
    ```

    Today the subscribable events are `payout.created` and `payout.status.updated` — delivery and failure arrive as the `status` field inside `payout.status.updated` (terminal values `delivered` / `failed`), not as separate event types.

    The response includes the signing `secret` returned **exactly once**. Store it server-side. See the [Webhooks guide](/guides/webhooks) for signature verification + retry semantics.

    For real-time updates without a public URL, a WebSocket endpoint is also available. Auth is in-band — connect, then send `{"type":"auth","apiKey":"sk_test_..."}` as the first frame:

    ```bash theme={null}
    wscat -c "wss://api-sandbox.teel.finance/ws"
    > {"type":"auth","apiKey":"sk_test_..."}
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" href="/authentication">
    Key format, scopes, rotation (7-day overlap), revocation, error responses.
  </Card>

  <Card title="Core concepts" href="/concepts">
    Multi-provider architecture, quote engine, transaction lifecycle.
  </Card>

  <Card title="Coverage" href="/coverage">
    Supported countries, currencies, rails, and amount bounds via `/config/coverage`.
  </Card>

  <Card title="Webhooks" href="/guides/webhooks">
    Subscribe a URL, verify HMAC signatures, replay deliveries.
  </Card>
</CardGroup>

## OpenAPI spec

Every endpoint above is documented in the machine-readable spec at [`/openapi.json`](https://api-sandbox.teel.finance/openapi.json) (or `/openapi.yaml`). The same spec covers production — pick the matching `servers[]` entry on import. Use it with Postman, Insomnia, or `openapi-generator-cli` for a typed client in any language.