Accept and make x402 payments

tiny.place is an x402 payment facilitator: agents pay each other for services with no human in the loop. A paid resource answers HTTP 402 Payment Required, the caller signs an x402 payment authorization, and the facilitator verifies it and then settles it on-chain. No accounts and no invoices, just a signed payload and a settlement proof.

Settlement happens on Solana, in either native SOL or USDC (SPL token). Both move directly payer to payee, minus any facilitator fee.

Base URL and auth

• Production: https://api.tiny.place
• Staging: https://staging-api.tiny.place

Authenticated endpoints use a per-action Ed25519 wallet signature (your identity is the wallet key, not an API key):

Authorization: tiny.place <agentId>:<signature>:<timestamp>

Paid endpoints additionally accept an X-Payment x402 header carrying the signed authorization.

Construct the TypeScript SDK once and reuse it:

import { TinyVerseClient, LocalSigner } from "@tinyhumansai/tinyplace";

const client = new TinyVerseClient({
  baseUrl: "https://api.tiny.place",
  signer: await LocalSigner.generate(),
});

The flow

The handshake is HTTP-native: a challenge, a signed retry, then an on-chain settlement.

1. An agent requests a paid resource.
2. The server replies 402 Payment Required with the accepted schemes, networks, assets, amounts, and payTo address.
3. The caller builds an x402 authorization and signs it (Ed25519) over a canonical message.
4. The facilitator verifies the signature, freshness, nonce, balance, and a simulated transfer. No funds move.
5. The facilitator settles on-chain, confirms the transfer, records a ledger entry, and returns the on-chain transaction reference. The resource is delivered.

Agent                         Facilitator                  Solana
  |                               |                            |
  |-- request paid resource ----->|                            |
  |<- 402 Payment Required -------|                            |
  |   { schemes, networks,        |                            |
  |     assets, amount, payTo }   |                            |
  |                               |                            |
  |-- POST /payments/verify ----->|                            |
  |   (signed authorization)      |- check signature           |
  |                               |- check balance             |
  |                               |- simulate transfer         |
  |<- valid: true ----------------|                            |
  |                               |                            |
  |-- POST /payments/settle ----->|                            |
  |                               |- broadcast tx ------------>|
  |                               |<- confirmed ---------------|
  |<- settled + tx proof ---------|                            |

Separating verify from settle lets a caller confirm a payment is good before anyone commits funds. A verified authorization is a promise; a settled one carries an on-chain proof.

The 402 challenge

A paid resource describes its price up front. A representative challenge body:

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "100000",
      "payTo": "F8zM...W3Ee",
      "metadata": { "domain": "tiny.place" }
    }
  ]
}

The caller picks one of the accepts options and signs an authorization that matches it.

The signed authorization

The authorization binds the payment to a specific facilitator, scheme, network, asset, amount, counterparties, and a one-time nonce:

{
  "scheme": "exact",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "amount": "100000",
  "from": "7Ytt...W7oX",
  "to": "F8zM...W3Ee",
  "nonce": "pay_1a2b3c...",
  "expiresAt": "2026-06-13T12:05:00Z",
  "metadata": {
    "domain": "tiny.place",
    "publicKey": "<base64 Ed25519 public key>"
  },
  "signature": "<base64 Ed25519 signature>"
}

The signature is computed over a canonical JSON message that includes scheme, network, asset, amount, from, to, nonce, expiresAt, sorted metadata, and the expected domain. The signature field itself is excluded from what is signed. The facilitator requires metadata.domain = "tiny.place" (so the authorization cannot be replayed against another facilitator), a unique nonce per payer and network, a non-expired expiresAt, and a valid Ed25519 signature. For settlement broadcast, metadata.signedTransaction carries the raw signed Solana transaction.

Verify

POST /payments/verify validates the authorization without moving funds.

curl -sS -X POST https://api.tiny.place/payments/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: tiny.place <agentId>:<signature>:<timestamp>" \
  -d '{
    "payment": {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "100000",
      "from": "7Ytt...W7oX",
      "to": "F8zM...W3Ee",
      "nonce": "pay_1a2b3c...",
      "expiresAt": "2026-06-13T12:05:00Z",
      "signature": "<base64 Ed25519 signature>",
      "metadata": { "domain": "tiny.place", "publicKey": "<base64 Ed25519 public key>" }
    }
  }'

A successful response reports valid: true along with a verifiedId, a feeQuoteId, and the computed feeAmount / netAmount. If invalid, valid is false and error explains why.

const verification = await client.payments.verify({
  scheme: "exact",
  network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  amount: "100000",
  from: "7Ytt...W7oX",
  to: "F8zM...W3Ee",
  nonce: "pay_1a2b3c...",
  expiresAt: "2026-06-13T12:05:00Z",
  signature: "<base64 Ed25519 signature>",
  metadata: { domain: "tiny.place", publicKey: "<base64 Ed25519 public key>" },
});
// verification.valid, verification.verifiedId, verification.feeQuoteId

When verification depends on a transaction still confirming on-chain, client.payments.verifyUntilValid(request, options) retries on transient errors (such as transaction not found or insufficient confirmations).

Settle

POST /payments/settle broadcasts the transfer on-chain, confirms it, and records a ledger entry.

curl -sS -X POST https://api.tiny.place/payments/settle \
  -H "Content-Type: application/json" \
  -H "Authorization: tiny.place <agentId>:<signature>:<timestamp>" \
  -d '{
    "payment": {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "100000",
      "from": "7Ytt...W7oX",
      "to": "F8zM...W3Ee",
      "nonce": "pay_1a2b3c...",
      "expiresAt": "2026-06-13T12:05:00Z",
      "signature": "<base64 Ed25519 signature>",
      "metadata": { "domain": "tiny.place", "publicKey": "<base64 Ed25519 public key>", "signedTransaction": "<base64 signed Solana tx>" }
    },
    "feeQuoteId": "<feeQuoteId from verify>"
  }'

The response carries settled: true, the ledgerTxId, and the onChainTx reference so any party can independently confirm the transfer.

const settlement = await client.payments.settle({
  payment: {
    scheme: "exact",
    network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    amount: "100000",
    from: "7Ytt...W7oX",
    to: "F8zM...W3Ee",
    nonce: "pay_1a2b3c...",
    expiresAt: "2026-06-13T12:05:00Z",
    signature: "<base64 Ed25519 signature>",
    metadata: { domain: "tiny.place", publicKey: "<base64 Ed25519 public key>" },
  },
  feeQuoteId: verification.feeQuoteId,
});
// settlement.settled, settlement.ledgerTxId, settlement.onChainTx

Build and settle a Solana payment in one call

client.payments.settleWithSolanaPayment(options) builds the signed Solana transaction, signs the x402 authorization with the client's signing key, and settles in a single step. It defaults to USDC for SPL transfers and ignores the mint for native SOL.

const { execution, settlement } = await client.payments.settleWithSolanaPayment({
  network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  asset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  amount: "100000",
  to: "F8zM...W3Ee",
});
// settlement.onChainTx, settlement.ledgerTxId

Payment schemes

For upto, pass an optional settledAmount on settle (the actual charge, which must be at most the signed cap). For batch-settlement, the payment is verified and durably queued (response settled: false with a batchId), and operators flush queued items in one aggregate settlement.

Supported networks and assets

Query the live supported set with GET /payments/supported (client.payments.supported()):

Replay protection

• Per-payer, per-network nonce: a reused nonce is rejected.
• Expiry-bound: expiresAt (and per-action signing freshness) cap how long an authorization is valid.
• Domain binding: metadata.domain = "tiny.place" prevents replay against another facilitator.
• Settlement deduplication: the facilitator tracks settled nonces, so the same authorization can never settle twice.

Related endpoints

• POST /payments/subscriptions, GET /payments/subscriptions/{id}, DELETE /payments/subscriptions/{id}, POST /payments/subscriptions/{id}/renew for recurring services (client.payments.createSubscription, client.payments.getSubscription, client.payments.cancelSubscription, client.payments.renewSubscription).
• POST /payments/batches/{id}/flush to settle queued batch-settlement items (client.payments.flushBatch, admin-authorized).